Skip to content

Commit

Permalink
[yaml-v2] Update Project Structure page
Browse files Browse the repository at this point in the history
  • Loading branch information
@costinsin
costinsin committed Mar 11, 2024
1 parent adf3f67 commit 0556936
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 84 deletions.
4 changes: 2 additions & 2 deletions docs/features/http-methods-webhooks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ A webhook/HTTP method is declared in the same way as any other genezio method, b
- The method must return a [`GenezioHttpResponse`](#geneziohttpresponse) object.

:::info
Decorators are only supported in TypeScript and JavaScript. If you are using any other supported language, you need to specify the method as an HTTP method in the `genezio.yaml` file.
Decorators are only supported in TypeScript and JavaScript. If you are using any other supported language, you need to specify the method as a HTTP method in the `genezio.yaml` file.
:::

<Tabs groupId="languages">
Expand Down Expand Up @@ -111,7 +111,7 @@ HTTP Methods Deployed:
#### Properties

- **headers - required:** A dictionary that contains the headers.
- **http - required:** An Object that has the following properties:
- **http - required:** An object that has the following properties:
- **method:** The HTTP method.
- **path:** The path of the request.
- **protocol:** The HTTP version used.
Expand Down
177 changes: 95 additions & 82 deletions docs/project-structure/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
sidebar_position: 5
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Admonition from '@theme/Admonition';

# Project Structure

There are 2 recommend ways of structuring your project:

1. In a fullstack single repository - all the files will be structured in a single repository/directory.
2. In component-dedicated repositories - the files will be structured in two distinct repositories/directories - a `server` and a `client` one.
1. Fullstack single repository - all the files will be placed in a single repository/directory.
2. Component-dedicated repositories - the files will be placed in multiple distinct repositories/directories - one `backend` and one or more `frontend` repositories.

The sections below help you understand what the approach to choose to make sense for your project and team's needs.
The sections below help you understand what the approach to choose that make sense for your project and team's needs.

## Single repository approach

A possible structure for a fullstack single repository can be:
You can use the [`genezio create fullstack`](../cli-tool/cli-commands/genezio-create.md) command to create a new project with the correct structure and configurations for a single repository project.

<!-- {% code title="Single repository" %} -->
A possible structure for a fullstack single repository can be:

```fallback title="Single repository"
.
Expand All @@ -34,108 +34,123 @@ A possible structure for a fullstack single repository can be:
└── package.json
```

<!-- {% endcode %} -->

Generally, genezio commands should be executed at the same location of the `genezio.yaml` configuration file.

Hence, for project structured in a single repository, commands such as `genezio deploy` and `genezio local` will be executed in the project's root directory.

Genezio is providing support for the concept of workspaces, so you can add in the `genezio.yaml` the paths to the corresponding server and client directories:

<!-- {% code title="genezio.yaml" %} -->
A possible `genezio.yaml` configuration file for a fullstack single repository can be:

```yaml title="genezio.yaml"
name: getting-started
region: us-east-1
language: ts
packageManager: npm
workspace:
backend: ./server
frontend: ./client
backend:
path: server
language:
name: ts
frontend:
path: client
language: ts
publish: dist
```
<!-- {% endcode %} -->
For more info on the `genezio.yaml` configuration file, check [genezio-configuration-file](genezio-configuration-file).

To correctly bundle and deploy your fullstack application, the directories paths must be set in the configuration file by setting the `workspace` field. If you start your project from genezio's official templates, this step will always be taken care for you.

For more info on the `genezio.yaml` configuration file, check [genezio-configuration-file](genezio-configuration-file "mention").

To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore "mention").
To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore).

## Multi-repository approach

This approach is useful when you want to decouple the development process of the frontend from and backend, allowing different teams to work independently of each other.

You can use the [`genezio create fullstack --multirepo`](../cli-tool/cli-commands/genezio-create.md) command to create a new project with the correct structure and configurations for a multi-repository project.

### The server repository

In the `server` repository you can add the source code related to the backend - classes, the configuration files for deploying the backend, environment variable files.
In the `server` repository you can add the source code related to the backend - classes, the configuration files for deploying the backend or environment variable files.

A possible structure for a multi-repository approach can be:

<!-- {% code title="Server repository" %} -->

```fallback title="Server repository"
.
└── server/
├── genezio.yaml
├── .genezioignore
├── .env
├── models/
├── node_modules/
├── package.json
└── index.ts
server/
├── genezio.yaml
├── .genezioignore
├── .env
├── models/
├── node_modules/
├── package.json
└── index.ts
```

<!-- {% endcode %} -->

To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore "mention").
To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore).

The minimum configuration file for the backend code to be deployed is:

<!-- {% code title="genezio.yaml" %} -->

```yaml title="genezio.yaml"
name: my-project-backend
region: us-east-1
language: ts
cloudProvider: genezio
scripts:
preBackendDeploy: npm install
packageManager: npm
name: my-project
backend:
path: .
language:
name: ts
scripts:
deploy: npm install
```

<!-- {% endcode %} -->

For more info on `genezio.yaml` check [genezio-configuration-file](genezio-configuration-file "mention").
For more info on `genezio.yaml` check [Genezio Configuration File](genezio-configuration-file).

### The client repository

In the client repository
In the `client` repository you can add the source code related to the frontend that will use the functions deployed in the backend.

<!-- {% code title="Client repository" %} -->
A possible structure for the frontend directory, using a multi-repository approach can be:

```fallback title="Client repository"
.
└── client/
├── genezio.yaml
├── .genezioignore
├── node_modules/
├── src/
├── build/
└── package.json
client/
├── genezio.yaml
├── .genezioignore
├── node_modules/
├── src/
├── build/
└── package.json
```

<!-- {% endcode %} -->

To install the genezio generated SDK in your to call your deployed methods, run:
The minimum configuration file for the frontend code to be deployed is:

```
npm install @genezio-sdk/<project-name>_<region>@1.0.0-<environment>
```yaml title="genezio.yaml"
name: my-project
frontend:
path: .
language: ts
```

This command will fetch the SDK from a private registry hosted on the genezio platform for you. For more information, check the [generated-sdk](../features/generated-sdk "mention") section.
<Admonition type="tip">
The project `name` defined in the `genezio.yaml` file should coincide in both the backend and frontend repositories.
</Admonition>

To connect to your backend while testing locally, you need to install the genezio generated SDK in the client repository. `genezio local` is able to install it automatically if you link your client repository path to a deployed project.
<Tabs groupId="languages">
<TabItem value="ts/js" label="TypeScript / JavaScript">
To install the genezio generated SDK in your frontend to call your deployed methods, run:

```
npm install @genezio-sdk/<project-name>@1.0.0-<environment>
```

This command will fetch the SDK from a private registry hosted on the genezio platform for you. For more information, check the [Generated SDK](../features/generated-sdk) section.

</TabItem>
<TabItem value="Other" label="Other supported languages">
To generate the SDK for your frontend, you can use the [`genezio generate-sdk`](../cli-tool/cli-commands/generatesdk.md) command. This command will generate the SDK for the frontend and place it in the `sdk` directory.

<Admonition type="tip">
You must have a backend deployed to generate the SDK.
</Admonition>

```sh title="Terminal"
genezio sdk --language <language> -o ./sdk
```

</TabItem>
</Tabs>

While developing locally, `genezio local` can hot-reload your Genezio SDK to reflect the changes in your backend code. This is useful for avoiding the need to manually generate the SDK every time you make changes to your backend code. For this to work, you need to tell genezio where your client repository is located, to be able to install the SDK automatically in that path.

To link your client repository to a deployed backend server, run:

Expand All @@ -145,20 +160,18 @@ genezio link --projectName <name> --region <region>

Alternatively, if you have a `genezio.yaml` configured in the client directory, the `genezio link` command can automatically infer the project name and region:

<!-- {% code title="genezio.yaml" %} -->

```yaml title="genezio.yaml"
name: my-project-server
name: my-project
region: us-east-1
frontend:
path: ./dist
path: .
language: ts
publish: dist
```

<!-- {% endcode %} -->

For more details on the genezio generated SDK, check out the section [generated-sdk](../features/generated-sdk "mention").
For more details on the genezio generated SDK, check out the section [Generated Sdk](../features/generated-sdk).

To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore "mention").
To ignore specific files while locally testing your project, you can use [.genezioignore](.genezioignore).

## Troubleshooting

Expand All @@ -168,14 +181,14 @@ If you encounter any errors or difficulties to test locally or deploy, check tha

`genezio deploy` and `genezio local` should always be executed at the same location where the `genezio.yaml` configuration file is saved.

`genezio link` or `genezio unlink` are specifically useful in a multi-repository structure. These commands are used to link/unlink the genezio generated SDK in the client directory.
`genezio link` or `genezio unlink` are specifically useful in a multi-repository structure. These commands are used to link/unlink the genezio Generated SDK in the client directory.

Depending on the project's structure (single repository or multi-repositories), you may need to update the paths for the:

- deployment scripts in the `genezio.yaml` file
- the frontend build directory
- the environment variables file
- deployment scripts in the `genezio.yaml` file
- the frontend `publish` directory
- the environment variables file

For more details and examples on how to correctly set the paths, check out the section [genezio-configuration-file](genezio-configuration-file "mention").
For more details and examples on how to correctly set the paths, check out the section [Genezio Configuration File](genezio-configuration-file).

Most of these settings are already taken care for you when starting from genezio's official templates or examples. Check out the [getting started](../getting-started "mention") tutorial to see how.
Most of these settings are already taken care for you when starting from genezio's official templates or examples. Check out the [Getting Started](../getting-started) tutorial to see how.

0 comments on commit 0556936

Please sign in to comment.