## 1. Project Overview & Quickstart (gluestack/CONTRIBUTING)
## 1. Project Overview & Quickstart (gluestack/CONTRIBUTING)
# CONTRIBUTING
Open-source repository gluestack/CONTRIBUTING
### Repository Details
- **Repository:** [gluestack/CONTRIBUTING](https://github.com/gluestack/CONTRIBUTING)
- **Primary Language:** Code
*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*
## 2. Official Technical Reference & Guides (gluestack/website)
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
## Getting Started
First, run the development server:
```bash
npm run dev
# or
yarn dev
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
## Learn More
To learn more about Next.js, take a look at the following resources:
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
## Deploy on Vercel
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
## 2. Official Technical Reference & Guides (gluestack/website)
## File: README.md
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
## Getting Started
First, run the development server:
```bash
npm run dev
# or
yarn dev
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
## Learn More
To learn more about Next.js, take a look at the following resources:
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
## Deploy on Vercel
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
---
## File: pages/docs/getting-started/installing-a-plugin-as-an-instance/index.mdx
import Meta from "@/components/Meta";
# Installing a Plugin as an Instance
You can pull the basic web template by running the following command.
```bash
node glue add web dashboard
```
The current version of the web plugin uses Next.js and the source code can be found at
`@gluestack/glue-plugin-web`on npm. This interactively takes the name of the web project. You may give it a name like `dashboard` or `landing`.
**Note:** You can create multiple web projects in the same gluestack app. We call them instances of web plugin.
```bash
node glue add web dashboard
> Installing 'web' from '@gluestack/glue-plugin-web'
? Select template: > - Use arrow-keys. Return to submit.
> next-gluestack-ts
next-tailwind-ts
next-ts
✔ Select template: > next-ts
> Sucessfully installed 'web' as instance dashboard in directory './dashboard'
```
---
## File: pages/docs/getting-started/building-rest-apis/index.mdx
import Meta from "@/components/Meta";
# Building REST APIs
This command helps you create a microservice in your gluestack project. To add a new service, you should run the following command:
```bash
node glue service:add
```
- This command will then ask you to "**Select a service plugin**" from a dropdown list. *Currently, we only support **@gluestack/glue-plugin-service-node** which is basically a microservice in NodeJS*
- Once you have selected the **service plugin**, then you will be asked to "**Enter the instance name**"
- That's it! Your new microservice with the provided name will be installed into your **backend/services** directory
```bash
node glue service:add
? Select a service plugin > - Use arrow-keys. Return to submit.
> @gluestack/glue-plugin-service-node - Select a language for your service
? Enter the instance name > todos-service
> Installing '@gluestack/glue-plugin-service-node' from '@gluestack/glue-plugin-service-node'
> Sucessfully installed '@gluestack/glue-plugin-service-node' as instance todos-service in directory './backend/services/todos-service'
```
## **The folder structure**
You get a express.js app in `backend/services/todos-service` with the following folder structure.
```bash
.env
.env.example
components
functions/
function/
health-check/
helpers/
package.json
router.js
server.js
```
On local dev, it will register routes such as:
```bash
Loaded route /function from function/handler.js
Loaded route /health-check from health-check/handler.js
```
## Adding a REST Endpoint
```bash
node glue function:add list-todos
****? Select a service plugin > - Use arrow-keys. Return to submit.
> @gluestack/glue-plugin-service-node - Select a language for your service
? Select an instance > - Use arrow-keys. Return to submit.
> todos-service - Select todos-service instance
✔ Select an instance > todos-service
```
## **The folder structure**
You get a list-todos function in functions
```bash
functions/
function/
health-check/
->new list-todos/
handler.js
```
On local dev, it will register a new route such as:
```bash
Loaded route /list-todos from list-todos/handler.js
```
---
## File: pages/docs/getting-started/building-graph-ql-apis/index.mdx
import Meta from "@/components/Meta";
# Building GraphQL APIs
This command helps you create a graphql workspace in your gluestack project.
After adding postgres instance, to add graphql, you should run the following command:
```bash
node glue add graphql graphql
```
- Your graphql instance will be installed into your **backend/services** directory
```bash
> Installing 'graphql' from '@gluestack/glue-plugin-graphql'
> Sucessfully installed 'graphql' as instance graphql in directory './backend/services/graphql'
```
## Attaching a REST Endpoint as GraphQL Action
This command helps you integrate a REST endpoint into a service and expose it as a GraphQL action. To add a new action, you should run the following command:
```bash
node glue function:attach-action
****? Select a service plugin > - Use arrow-keys. Return to submit.
> @gluestack/glue-plugin-service-node - Select a language for your service
? Select an instance > - Use arrow-keys. Return to submit.
> todos-services - Select auth-services instance
? Select a function > - Use arrow-keys. Return to submit.
> list-todos
function
health-check
```
## **The folder structure**
You got two new files in **list-todos** function
```bash
list-todos/
->new action.graphql
->new action.setting
handler.js
```
---
## File: pages/docs/getting-started/bootstrap-project/index.mdx
import Meta from "@/components/Meta";
# Bootstrap Project
## Create a gluestack app.
```bash
npx create-gluestack-app@latest my-gluestack-app
```
## The folder structure
You get a basic gluestack app with the following folder structure. This is a Node project. (This isn't a monorepo yet).
```bash
.env
glue
meta/
package.json
```
### **The meta folder**
This folder keeps the config that's needed by the framework. Plugins use this folder to store their persistent information too.
### **The glue command**
This is a Node.js file, a command that points to the CLI of the locally installed framework. We can use this by running `node glue`. Try it out to list the commands that are registered.
### **The package.json file**
Since the create-project command scaffolds a Node project, all the dependencies and its related information are stored in `package.json` file.
---
## File: pages/docs/getting-started/adding-web/index.mdx
import Meta from "@/components/Meta";
# Adding Web
This command helps you create a frontend workspace in your gluestack project.
```bash
node glue add web website
> Installing 'web' from '@gluestack/glue-plugin-web'
? Select template: > - Use arrow-keys. Return to submit.
> next-gluestack-ts
next-tailwind-ts
next-ts
✔ Select template: > next-ts
> Sucessfully installed 'web' as instance admin in directory './website'
```
## **The folder structure**
You get a Next.js app in `website` with the following folder structure.
```bash
.env
next.config.js
package.json
pages/
public/
router.js
styles
tsconfig.json
```
### **The** pages **folder**
In Next.js, a **page** is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory. Each page is associated with a route based on its file name.
**Example**: If you create `pages/about.js` that exports a React component like below, it will be accessible at `/about`.
```jsx
export default function About() {
return About
}
```
### **The router.js file**
This file is treated as the upstream in the nginx configuration. It accepts following params in an array format:
- **path**: The path to match on
- **proxy**: The proxy configuration
- **proxy.path**: The path to match on the proxied configuration
- **size_in_mb**: The maximum size of the request body in megabytes, default is 50 mb
```jsx
module.exports = () => [
{
server_name: "website"
},
{
path: '/(.*)',
proxy: {
path: '/$1',
instance: "website:9000",
},
size_in_mb: '50',
},
];
```
### **The package.json file**
Since the add web command scaffolds a Next.js project, all the dependencies and its related information are stored in `package.json` file.
---
## File: pages/docs/getting-started/adding-deploy/index.mdx
import Meta from "@/components/Meta";
# Add deploy
This command helps you deploy your gluestack app to our Seal platform. To add deploy, you should run the following command:
```bash
node glue add deploy deploy
> Installing 'deploy' from '@gluestack/glue-plugin-deploy'
> Sucessfully installed 'deploy' as instance deploy in directory ''
```
Running `node glue deploy` command will deploy all the frontend and backend services provided by gluestack.
---
## File: pages/docs/getting-started/adding-backend/index.mdx
import Meta from "@/components/Meta";
# Adding Backend
This command helps you configure backend engine in your gluestack porject.
```bash
node glue add backend-engine engine
> Installing 'backend-engine' from '@gluestack/glue-plugin-backend-engine'
> Sucessfully installed 'backend-engine' as instance engine in directory './backend/engine'
```
## **The folder structure**
You get a express.js app in `backend/engine` with the following folder structure.
```bash
.env
components
package.json
router.js
src/
```
## The **backend directory**
- **backend** directory if it does not exists in your gluestack project's root directory
- **backend/crons** directory with **crons.json** file which contains all your project specific CRONs
- **backend/events** directory with **app** and **database** sub-directories all your project specific events
- **backend/events/app** directory will contain all the app events
- **backend/events/database** directory will contain all the database events
- **backend/engine** directory contains the **gluestack backend engine server** which manages **Events**, **Crons** & **Queues**
### **The router.js file**
This file is treated as the upstream in the nginx configuration.
```jsx
module.exports = () => {
return [
{
"path": "/backend/engine/(.*)",
"proxy": {
"instance": "engine:3500",
"path": "/v1.0/invoke/engine/method/$1"
}
}
];
};
```
### **The package.json file**
Since the add backend-engine command scaffolds a express.js project, all the dependencies and its related information are stored in `package.json` file.
---
## File: pages/docs/overview/prerequisites/index.mdx
import Meta from "@/components/Meta";
# Prerequisites
## Prior knowledge
It's good to have a working hands-on of the following to use the core plugins by gluestack.
- Next.js (React)
- GraphQL (Hasura preferred)
- SQL
gluestack also comes in with `gluestack/ui` which is similar to other famous React-based UI libraries.
## Minimum system requirements
- Node 18.x (>= 18 & < 19)
- Latest Docker 4.1.6
- Docker Engine 20.10.22
---
## File: pages/docs/overview/philosophy/index.mdx
import Meta from "@/components/Meta";
# **Philosophy**
This project is guided by a set of principles that inform our decision-making and shape our approach to building.
### **Innovate Carefully**
We embrace new and innovative technologies, but we also recognize that they can bring risks and challenges. We therefore approach their use with care, carefully considering their potential benefits and drawbacks before incorporating them into our projects. For example, we might be hesitant to use untested database technologies. Still, we are willing to experiment with GraphQL and Cloud functions because they are relatively easy to change if needed.
### **No compromise on performance**
Performance is a top priority for us. We understand that even a slight degradation in performance can have a significant impact on the user experience. We, therefore, strive to optimize our systems and processes to deliver the best possible performance.
### **Developer Experience**
We believe that the developer experience is just as important as the user experience. We aim to create a smooth and enjoyable workflow for developers with tools and processes that are intuitive and efficient.
### **Architecture first, language independent**
Our focus is on building solid and scalable architectures, rather than relying on specific programming languages. This allows us to choose the right tools and technologies for the job, rather than being constrained by a particular language or ecosystem.
We have two parts to the gluestack framework: the core and the opinions.
## **Part 1: The core**
The core is guided by the following principles:
- Architecture first, language independent
- Bring what you want
- Loosely coupled
The core provides the basic structure for initializing a gluestack project and an environment for using and building plugins. Our first decision was to use NPM as the package manager for initializing projects and plugins. Our second decision was to use Docker when moving out of the Node and JS ecosystem to provide the development environment and boot-up dependent services.
Note: This does not mean that the core requires the use of JavaScript or TypeScript to build a gluestack app. That is the role of Part 2.
## **Part 2: The opinions (that comes with the core plugins)**
Our opinions are based on our experience running an app development agency and building hundreds of web and mobile apps. Our goal is not to include everything under the sun, but rather to address specific issues within the core technologies.
For example, we will not add state libraries like zustand or redux, but we will include something like NextAuth.js and integrate Hasura and GraphQL for you.
Our opinions also aim to bring standardization to the development process and utilize proven technologies.
These opinions are guided by the following principles:
- Solve for most, but not all
- Adopt the best
- Come with no lock-in