feat(db): mesh data model — meshes, members, invites, audit log
- pgSchema "mesh" with 4 tables isolating the peer mesh domain - Enums: visibility, transport, tier, role - audit_log is metadata-only (E2E encryption enforced at broker/client) - Cascade on mesh delete, soft-delete via archivedAt/revokedAt Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Cloning repository
|
||||
description: Get the code to your local machine and start developing.
|
||||
url: /docs/web/installation/clone
|
||||
---
|
||||
|
||||
# Cloning repository
|
||||
|
||||
<Callout type="info" title="Prerequisite: Git installed">
|
||||
Ensure you have Git installed on your local machine before proceeding. You can download Git from [here](https://git-scm.com).
|
||||
</Callout>
|
||||
|
||||
## Git clone
|
||||
|
||||
Clone the repository using the following command:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:turbostarter/core
|
||||
```
|
||||
|
||||
By default, we're using [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for all Git commands. If you don't have it configured, please refer to the [official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) to set it up.
|
||||
|
||||
Alternatively, you can use HTTPS to clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/turbostarter/core
|
||||
```
|
||||
|
||||
Another alternative could be to use the [Github CLI](https://cli.github.com/) or [Github Desktop](https://desktop.github.com/) for Git operations.
|
||||
|
||||
<Card title="Git clone" description="git-scm.com" href="https://git-scm.com/docs/git-clone" />
|
||||
|
||||
## Git remote
|
||||
|
||||
After cloning the repository, remove the original origin remote:
|
||||
|
||||
```bash
|
||||
git remote rm origin
|
||||
```
|
||||
|
||||
Add the upstream remote pointing to the original repository to pull updates:
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:turbostarter/core
|
||||
```
|
||||
|
||||
Once you have your own repository set up, add your repository as the origin:
|
||||
|
||||
```bash
|
||||
git remote add origin <your-repository-url>
|
||||
```
|
||||
|
||||
<Card title="Git remote" description="git-scm.com" href="https://git-scm.com/docs/git-remote" />
|
||||
|
||||
## Staying up to date
|
||||
|
||||
To pull updates from the upstream repository, run the following command daily (preferably with your morning coffee ☕):
|
||||
|
||||
```bash
|
||||
git pull upstream main
|
||||
```
|
||||
|
||||
This ensures your repository stays up to date with the latest changes.
|
||||
|
||||
Check [Updating codebase](/docs/web/installation/update) for more details on updating your codebase.
|
||||
@@ -0,0 +1,353 @@
|
||||
---
|
||||
title: Common commands
|
||||
description: Learn about common commands you need to know to work with the project.
|
||||
url: /docs/web/installation/commands
|
||||
---
|
||||
|
||||
# Common commands
|
||||
|
||||
<Callout>
|
||||
For sure, you don't need these commands to kickstart your project, but it's useful to know they exist for when you need them.
|
||||
</Callout>
|
||||
|
||||
<Callout title="Want shorter commands?">
|
||||
You can set up aliases for these commands in your shell configuration file. For example, you can set up an alias for `pnpm` to `p`:
|
||||
|
||||
```bash title="~/.bashrc"
|
||||
alias p='pnpm'
|
||||
```
|
||||
|
||||
Or, if you're using [Zsh](https://ohmyz.sh/), you can add the alias to `~/.zshrc`:
|
||||
|
||||
```bash title="~/.zshrc"
|
||||
alias p='pnpm'
|
||||
```
|
||||
|
||||
Then run `source ~/.bashrc` or `source ~/.zshrc` to apply the changes.
|
||||
|
||||
You can now use `p` instead of `pnpm` in your terminal. For example, `p i` instead of `pnpm install`.
|
||||
</Callout>
|
||||
|
||||
<Callout title="Injecting environment variables">
|
||||
To inject environment variables into the command you run, prefix it with `with-env`:
|
||||
|
||||
```bash
|
||||
pnpm with-env <command>
|
||||
```
|
||||
|
||||
For example, `pnpm with-env pnpm build` will run `pnpm build` with the environment variables injected.
|
||||
|
||||
Some commands, like `pnpm dev`, automatically inject the environment variables for you.
|
||||
</Callout>
|
||||
|
||||
## Installing dependencies
|
||||
|
||||
To install the dependencies, run:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Starting development server
|
||||
|
||||
Start development server by running:
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Building project
|
||||
|
||||
To build the project (including all apps and packages), run:
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## Building specific app/package
|
||||
|
||||
To build a specific app/package, run:
|
||||
|
||||
```bash
|
||||
pnpm turbo build --filter=<package-name>
|
||||
```
|
||||
|
||||
## Cleaning project
|
||||
|
||||
To clean the project, run:
|
||||
|
||||
```bash
|
||||
pnpm clean
|
||||
```
|
||||
|
||||
Then, reinstall the dependencies:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Formatting code
|
||||
|
||||
To check for formatting errors using Prettier, run:
|
||||
|
||||
```bash
|
||||
pnpm format
|
||||
```
|
||||
|
||||
To fix formatting errors using Prettier, run:
|
||||
|
||||
```bash
|
||||
pnpm format:fix
|
||||
```
|
||||
|
||||
## Linting code
|
||||
|
||||
To check for linting errors using ESLint, run:
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
To fix linting errors using ESLint, run:
|
||||
|
||||
```bash
|
||||
pnpm lint:fix
|
||||
```
|
||||
|
||||
## Typechecking
|
||||
|
||||
To typecheck the code using TypeScript for any type errors, run:
|
||||
|
||||
```bash
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
## Adding UI components
|
||||
|
||||
<Tabs items={["Web", "Mobile"]}>
|
||||
<Tab value="Web">
|
||||
To add a new web component, run:
|
||||
|
||||
```bash
|
||||
pnpm --filter @turbostarter/ui-web ui:add
|
||||
```
|
||||
|
||||
This command will add and export a new component to `@turbostarter/ui-web` package.
|
||||
</Tab>
|
||||
|
||||
<Tab value="Mobile">
|
||||
To add a new mobile component, run:
|
||||
|
||||
```bash
|
||||
pnpm --filter @turbostarter/ui-mobile ui:add
|
||||
```
|
||||
|
||||
This command will add and export a new component to `@turbostarter/ui-mobile` package.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Services commands
|
||||
|
||||
<Callout title="Prerequisite: Docker installed">
|
||||
To run the services containers locally, you need to have [Docker](https://www.docker.com/) installed on your machine.
|
||||
|
||||
You can always use the cloud-hosted solution (e.g. [Neon](https://neon.tech/), [Turso](https://turso.tech/) for database) for your projects.
|
||||
</Callout>
|
||||
|
||||
We have a few commands to help you manage the services containers (for local development).
|
||||
|
||||
### Starting containers
|
||||
|
||||
To start the services containers, run:
|
||||
|
||||
```bash
|
||||
pnpm services:start
|
||||
```
|
||||
|
||||
It will run all the services containers. You can check their configs in `docker-compose.yml`.
|
||||
|
||||
### Setting up services
|
||||
|
||||
To setup all the services, run:
|
||||
|
||||
```bash
|
||||
pnpm services:setup
|
||||
```
|
||||
|
||||
It will start all the services containers and run necessary setup steps.
|
||||
|
||||
### Stopping containers
|
||||
|
||||
To stop the services containers, run:
|
||||
|
||||
```bash
|
||||
pnpm services:stop
|
||||
```
|
||||
|
||||
### Displaying status
|
||||
|
||||
To check the status and logs of the services containers, run:
|
||||
|
||||
```bash
|
||||
pnpm services:status
|
||||
```
|
||||
|
||||
### Displaying logs
|
||||
|
||||
To display the logs of the services containers, run:
|
||||
|
||||
```bash
|
||||
pnpm services:logs
|
||||
```
|
||||
|
||||
### Database commands
|
||||
|
||||
We have a few commands to help you manage the database leveraging [Drizzle CLI](https://orm.drizzle.team/kit-docs/commands).
|
||||
|
||||
#### Generating migrations
|
||||
|
||||
To generate a new migration, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env turbo db:generate
|
||||
```
|
||||
|
||||
It will create a new migration `.sql` file in the `packages/db/migrations` folder.
|
||||
|
||||
#### Running migrations
|
||||
|
||||
To run the migrations against the db, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:migrate
|
||||
```
|
||||
|
||||
It will apply all the pending migrations.
|
||||
|
||||
#### Pushing changes directly
|
||||
|
||||
<Callout type="warn" title="Don't mess up with your schema!">
|
||||
Make sure you know what you're doing before pushing changes directly to the db.
|
||||
</Callout>
|
||||
|
||||
To push changes directly to the db, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:push
|
||||
```
|
||||
|
||||
It lets you push your schema changes directly to the database and omit managing SQL migration files.
|
||||
|
||||
#### Checking database status
|
||||
|
||||
To check the status of the database, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:status
|
||||
```
|
||||
|
||||
It will display the status of the applied migrations and the pending ones.
|
||||
|
||||
```bash
|
||||
Applied migrations:
|
||||
- 0000_cooing_vargas
|
||||
- 0001_curious_wallflower
|
||||
- 0002_good_vertigo
|
||||
- 0003_peaceful_devos
|
||||
- 0004_fat_mad_thinker
|
||||
- 0005_yummy_bucky
|
||||
- 0006_glorious_vargas
|
||||
|
||||
Pending migrations:
|
||||
- 0007_nebulous_havok
|
||||
```
|
||||
|
||||
#### Resetting database
|
||||
|
||||
To reset the database, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:reset
|
||||
```
|
||||
|
||||
It will reset the database to the initial state.
|
||||
|
||||
#### Seeding database
|
||||
|
||||
To seed the database with some example data (for development purposes), run:
|
||||
|
||||
```bash
|
||||
pnpm with-env turbo db:seed
|
||||
```
|
||||
|
||||
It will populate your database with some example data.
|
||||
|
||||
#### Checking database
|
||||
|
||||
To check the database schema consistency, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:check
|
||||
```
|
||||
|
||||
#### Studying database
|
||||
|
||||
To study the database schema in the browser, run:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:studio
|
||||
```
|
||||
|
||||
This will start the Studio on [https://local.drizzle.studio](https://local.drizzle.studio).
|
||||
|
||||
## Tests commands
|
||||
|
||||
### Running tests
|
||||
|
||||
To run the tests, run:
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
This will run all the tests in the project using Turbo tasks. As it leverages Turbo caching, it's [recommended](/docs/web/tests/unit#configuration) to run it in your CI/CD pipeline.
|
||||
|
||||
### Running tests projects
|
||||
|
||||
To run tests for all Vitest [Test Projects](https://vitest.dev/guide/projects), run:
|
||||
|
||||
```bash
|
||||
pnpm test:projects
|
||||
```
|
||||
|
||||
This will run all the tests in the project using Vitest.
|
||||
|
||||
### Watching tests
|
||||
|
||||
To watch the tests, run:
|
||||
|
||||
```bash
|
||||
pnpm test:projects:watch
|
||||
```
|
||||
|
||||
This will watch the tests for all [Test Projects](https://vitest.dev/guide/projects) and run them automatically when you make changes.
|
||||
|
||||
### Generating code coverage
|
||||
|
||||
To generate code coverage report, run:
|
||||
|
||||
```bash
|
||||
pnpm turbo test:coverage
|
||||
```
|
||||
|
||||
This will generate a code coverage report in the `coverage` directory under `tooling/vitest` package.
|
||||
|
||||
### Viewing code coverage
|
||||
|
||||
To preview the code coverage report in the browser, run:
|
||||
|
||||
```bash
|
||||
pnpm turbo test:coverage:view
|
||||
```
|
||||
|
||||
This will launch the report's `.html` file in your default browser.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Conventions
|
||||
description: Some standard conventions used across TurboStarter codebase.
|
||||
url: /docs/web/installation/conventions
|
||||
---
|
||||
|
||||
# Conventions
|
||||
|
||||
You're not required to follow these conventions: they're simply a standard set of practices used in the core kit. If you like them - we encourage you to keep these during your usage of the kit - so to have consistent code style that you and your teammates understand.
|
||||
|
||||
## Turborepo Packages
|
||||
|
||||
In this project, we use [Turborepo packages](https://turbo.build/repo/docs/core-concepts/internal-packages) to define reusable code that can be shared across multiple applications.
|
||||
|
||||
* **Apps** are used to define the main application, including routing, layout, and global styles.
|
||||
* **Packages** shares reusable code add functionalities across multiple applications. They're configurable from the main application.
|
||||
|
||||
<Callout title="Should I create a new package?">
|
||||
**Recommendation:** Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.
|
||||
|
||||
If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.
|
||||
|
||||
**Experienced developers:** If you have the experience, feel free to create packages as needed.
|
||||
</Callout>
|
||||
|
||||
## Imports and Paths
|
||||
|
||||
When importing modules from packages or apps, use the following conventions:
|
||||
|
||||
* **From a package:** Use `@turbostarter/package-name` (e.g., `@turbostarter/ui`, `@turbostarter/api`, etc.).
|
||||
* **From an app:** Use `~/` (e.g., `~/components`, `~/config`, etc.).
|
||||
|
||||
## Enforcing conventions
|
||||
|
||||
* [Prettier](https://prettier.io/) is used to enforce code formatting.
|
||||
* [ESLint](https://eslint.org/) is used to enforce code quality and best practices.
|
||||
* [TypeScript](https://www.typescriptlang.org/) is used to enforce type safety.
|
||||
|
||||
<Cards className="grid-cols-2 sm:grid-cols-3">
|
||||
<Card title="Prettier" href="https://prettier.io/" description="prettier.io" />
|
||||
|
||||
<Card title="ESLint" href="https://eslint.org/" description="eslint.org" />
|
||||
|
||||
<Card title="TypeScript" href="https://www.typescriptlang.org/" description="typescriptlang.org" />
|
||||
</Cards>
|
||||
|
||||
## Code health
|
||||
|
||||
TurboStarter provides a set of tools to ensure code health and quality in your project.
|
||||
|
||||
### Github Actions
|
||||
|
||||
By default, TurboStarter sets up Github Actions to run tests on every push to the repository. You can find the Github Actions configuration in the `.github/workflows` directory.
|
||||
|
||||
The workflow has multiple stages:
|
||||
|
||||
* `format` - runs Prettier to format the code.
|
||||
* `lint` - runs ESLint to check for linting errors.
|
||||
* `typecheck` - runs TypeScript to check for type errors.
|
||||
|
||||
### Git hooks
|
||||
|
||||
Together with TurboStarter we have set up a `commit-msg` hook which will check if your commit message follows the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) message format. This is important for generating changelogs and keeping a clean commit history.
|
||||
|
||||
Although we didn't ship any pre-commit hooks (we believe in shipping fast with moving checking code responsibility to CI), you can easily add them by using [Husky](https://typicode.github.io/husky/#/).
|
||||
|
||||
#### Setting up the Pre-Commit Hook
|
||||
|
||||
To do so, create a `pre-commit` file in the `./..husky` directory with the following content:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
pnpm typecheck
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
Turborepo will execute the commands for all the affected packages - while skipping the ones that are not affected.
|
||||
|
||||
#### Make the Pre-Commit Hook Executable
|
||||
|
||||
```bash
|
||||
chmod +x ./.husky/pre-commit
|
||||
```
|
||||
|
||||
To test the pre-commit hook, try to commit a file with linting errors or type errors. The commit should fail, and you should see the error messages in the console.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Managing dependencies
|
||||
description: Learn how to manage dependencies in your project.
|
||||
url: /docs/web/installation/dependencies
|
||||
---
|
||||
|
||||
# Managing dependencies
|
||||
|
||||
As the package manager we chose [pnpm](https://pnpm.io/).
|
||||
|
||||
<Callout title="Why pnpm?">
|
||||
It is a fast, disk space efficient package manager that uses hard links and symlinks to save one version of a module only ever once on a disk. It also has a great [monorepo support](https://pnpm.io/workspaces). Of course, you can change it to use [Bun](https://bunpkg.com), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) with minimal effort.
|
||||
</Callout>
|
||||
|
||||
## Install dependency
|
||||
|
||||
To install a package you need to decide whether you want to install it to the root of the monorepo or to a specific workspace. Installing it to the root makes it available to all packages, while installing it to a specific workspace makes it available only to that workspace.
|
||||
|
||||
To install a package globally, run:
|
||||
|
||||
```bash
|
||||
pnpm add -w <package-name>
|
||||
```
|
||||
|
||||
To install a package to a specific workspace, run:
|
||||
|
||||
```bash
|
||||
pnpm add --filter <workspace-name> <package-name>
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
pnpm add --filter @turbostarter/ui motion
|
||||
```
|
||||
|
||||
It will install `motion` to the `@turbostarter/ui` workspace.
|
||||
|
||||
## Remove dependency
|
||||
|
||||
Removing a package is the same as installing but with the `remove` command.
|
||||
|
||||
To remove a package globally, run:
|
||||
|
||||
```bash
|
||||
pnpm remove -w <package-name>
|
||||
```
|
||||
|
||||
To remove a package from a specific workspace, run:
|
||||
|
||||
```bash
|
||||
pnpm remove --filter <workspace-name> <package-name>
|
||||
```
|
||||
|
||||
## Update a package
|
||||
|
||||
Updating is a bit easier since there is a nice way to update a package in all workspaces at once:
|
||||
|
||||
```bash
|
||||
pnpm update -r <package-name>
|
||||
```
|
||||
|
||||
<Callout title="Semantic versioning">
|
||||
When you update a package, pnpm will respect the [semantic versioning](https://docs.npmjs.com/about-semantic-versioning) rules defined in the `package.json` file. If you want to update a package to the latest version, you can use the `--latest` flag.
|
||||
</Callout>
|
||||
|
||||
## Renovate bot
|
||||
|
||||
By default, TurboStarter comes with [Renovate](https://www.npmjs.com/package/renovate) enabled. It is a tool that helps you manage your dependencies by automatically creating pull requests to update your dependencies to the latest versions. You can find its configuration in the `.github/renovate.json` file. Learn more about it in the [official docs](https://docs.renovatebot.com/configuration-options/).
|
||||
|
||||
When it creates a pull request, it is treated as a normal PR, so all tests and preview deployments will run. **It is recommended to always preview and test the changes in the staging environment before merging the PR to the main branch to avoid breaking the application.**
|
||||
|
||||
<Card href="https://docs.renovatebot.com" title="Renovate" description="renovatebot.com" />
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Development
|
||||
description: Get started with the code and develop your SaaS.
|
||||
url: /docs/web/installation/development
|
||||
---
|
||||
|
||||
# Development
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To get started with TurboStarter, ensure you have the following installed and set up:
|
||||
|
||||
* [Node.js](https://nodejs.org/en) (22.x or higher)
|
||||
* [Docker](https://www.docker.com) (only if you want to use local services e.g. database)
|
||||
* [pnpm](https://pnpm.io)
|
||||
|
||||
## Project development
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Install dependencies
|
||||
|
||||
Install the project dependencies by running the following command:
|
||||
|
||||
```bash
|
||||
pnpm i
|
||||
```
|
||||
|
||||
<Callout title="Why pnpm?">
|
||||
It is a fast, disk space efficient package manager that uses hard links and symlinks to save one version of a module only ever once on a disk. It also has a great [monorepo support](https://pnpm.io/workspaces). Of course, you can change it to use [Bun](https://bunpkg.com), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) with minimal effort.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Setup environment variables
|
||||
|
||||
Create a `.env.local` files from `.env.example` files and fill in the required environment variables.
|
||||
|
||||
You can use the following command to recursively copy the `.env.example` files to the `.env.local` files:
|
||||
|
||||
<Tabs items={["Unix (MacOS/Linux)", "Windows"]}>
|
||||
<Tab value="Unix (MacOS/Linux)">
|
||||
```bash
|
||||
find . -name ".env.example" -exec sh -c 'cp "$1" "${1%.example}.local"' _ {} \;
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="Windows">
|
||||
```bash
|
||||
Get-ChildItem -Recurse -Filter ".env.example" | ForEach-Object {
|
||||
Copy-Item $_.FullName ($\_.FullName -replace '\.example$', '.local')
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Check [Environment variables](/docs/web/configuration/environment-variables) for more details on setting up environment variables.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Setup services
|
||||
|
||||
If you want to use local services like [database](/docs/web/database/overview) (**recommended for development purposes**), ensure Docker is running, then setup them with:
|
||||
|
||||
```bash
|
||||
pnpm services:setup
|
||||
```
|
||||
|
||||
This command initiates the containers and runs necessary setup steps, ensuring your services are up to date and ready to use.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Start development server
|
||||
|
||||
To start the application development server, run:
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Your app should now be up and running at [http://localhost:3000](http://localhost:3000) 🎉
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Deploy to Production
|
||||
|
||||
When you're ready to deploy the project to production, follow the [checklist](/docs/web/deployment/checklist) to ensure everything is set up correctly.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Editor setup
|
||||
description: Learn how to set up your editor for the fastest development experience.
|
||||
url: /docs/web/installation/editor-setup
|
||||
---
|
||||
|
||||
# Editor setup
|
||||
|
||||
Of course you can use every IDE you like, but you will have the best possible developer experience with this starter kit when using **VSCode-based** editor with the suggested settings and extensions.
|
||||
|
||||
## Settings
|
||||
|
||||
We have included most recommended settings in the `.vscode/settings.json` file to make your development experience as smooth as possible. It include mostly configs for tools like Prettier, ESLint and Tailwind which are used to enforce some conventions across the codebase. You can adjust them to your needs.
|
||||
|
||||
## LLM rules
|
||||
|
||||
We exposed a special endpoint that will scan all the docs and return the content as a text file which you can use to train your LLM or put in a prompt. You can find it at [/llms.txt](/llms.txt).
|
||||
|
||||
The repository also includes a custom rules for most popular AI editors and agents to ensure that AI completions are working as expected and following our conventions.
|
||||
|
||||
### AGENTS.md
|
||||
|
||||
We've integrated specific rules that help maintain code quality and ensure AI-assisted completions align with our project standards.
|
||||
|
||||
You can find them in the `AGENTS.md` file at the root of the project. This format is a standardized way to instruct AI agents to follow project conventions when generating code and it's used by over **20,000** open-source projects - including [Cursor](https://cursor.sh/), [Aider](https://aider.chat/), [Codex from OpenAI](https://openai.com/blog/openai-codex/), [Jules from Google](https://jules.ai/), [Windsurf](https://windsurf.dev/), and many others.
|
||||
|
||||
```md title="AGENTS.md"
|
||||
### Code Style and Structure
|
||||
|
||||
- Write concise, technical TypeScript code with accurate examples
|
||||
- Use functional and declarative programming patterns; avoid classes
|
||||
- Prefer iteration and modularization over code duplication
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
....
|
||||
```
|
||||
|
||||
To learn more about `AGENTS.md` rules check out the [official documentation](https://agents.md/).
|
||||
|
||||
## Extensions
|
||||
|
||||
Once you cloned the project and opened it in VSCode you should be promted to install suggested extensions which are defined in the `.vscode/extensions.json` automatically. In case you rather want to install them manually you can do so at any time later.
|
||||
|
||||
These are the extensions we recommend:
|
||||
|
||||
### ESLint
|
||||
|
||||
Global extension for static code analysis. It will help you to find and fix problems in your JavaScript code.
|
||||
|
||||
<Card title="Download ESLint" href="https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint" description="marketplace.visualstudio.com" />
|
||||
|
||||
### Prettier
|
||||
|
||||
Global extension for code formatting. It will help you to keep your code clean and consistent.
|
||||
|
||||
<Card title="Download Prettier" href="https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode" description="marketplace.visualstudio.com" />
|
||||
|
||||
### Pretty TypeScript Errors
|
||||
|
||||
Improves TypeScript error messages shown in the editor.
|
||||
|
||||
<Card title="Download Pretty TypeScript Errors" href="https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors" description="marketplace.visualstudio.com" />
|
||||
|
||||
### Tailwind CSS IntelliSense
|
||||
|
||||
Adds IntelliSense for Tailwind CSS classes to enable autocompletion and linting.
|
||||
|
||||
<Card title="Download Tailwind CSS IntelliSense" href="https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss" description="marketplace.visualstudio.com" />
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Project structure
|
||||
description: Learn about the project structure and how to navigate it.
|
||||
url: /docs/web/installation/structure
|
||||
---
|
||||
|
||||
# Project structure
|
||||
|
||||
The main directories in the project are:
|
||||
|
||||
* `apps` - the location of the main apps
|
||||
* `packages` - the location of the shared code and the API
|
||||
|
||||
### `apps` Directory
|
||||
|
||||
This is where the apps live. It includes web app (Next.js), mobile app (React Native - Expo), and the browser extension (WXT - Vite + React). Each app has its own directory.
|
||||
|
||||
### `packages` Directory
|
||||
|
||||
This is where the shared code and the API for packages live. It includes the following:
|
||||
|
||||
* shared libraries (database, mailers, cms, billing, etc.)
|
||||
* shared features (auth, mails, billing, ai etc.)
|
||||
* UI components (buttons, forms, modals, etc.)
|
||||
|
||||
All apps can use and reuse the API exported from the packages directory. This makes it easy to have one, or many apps in the same codebase, sharing the same code.
|
||||
|
||||
## Repository structure
|
||||
|
||||
By default the monorepo contains the following apps and packages:
|
||||
|
||||
<Files>
|
||||
<Folder name="apps" defaultOpen>
|
||||
<Folder name="web - Web app (Next.js)" />
|
||||
|
||||
<Folder name="mobile - Mobile app (React Native - Expo)" />
|
||||
|
||||
<Folder name="extension - Browser extension (WXT - Vite + React)" />
|
||||
</Folder>
|
||||
|
||||
<Folder name="packages" defaultOpen>
|
||||
<Folder name="analytics - Analytics setup" />
|
||||
|
||||
<Folder name="api - API server (including all features logic)" />
|
||||
|
||||
<Folder name="auth - Authentication setup" />
|
||||
|
||||
<Folder name="billing - Billing config and providers" />
|
||||
|
||||
<Folder name="cms - CMS setup and providers" />
|
||||
|
||||
<Folder name="db - Database setup" />
|
||||
|
||||
<Folder name="email - Mail templates and providers" />
|
||||
|
||||
<Folder name="i18n - Internationalization setup" />
|
||||
|
||||
<Folder name="shared - Shared utilities and helpers" />
|
||||
|
||||
<Folder name="storage - Storage setup" />
|
||||
|
||||
<Folder name="ui - Atomic UI components">
|
||||
<Folder name="shared" />
|
||||
|
||||
<Folder name="web" />
|
||||
|
||||
<Folder name="mobile" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
|
||||
<Folder name="tooling" defaultOpen>
|
||||
<Folder name="eslint - ESLint config" />
|
||||
|
||||
<Folder name="github - Github actions" />
|
||||
|
||||
<Folder name="prettier - Prettier config" />
|
||||
|
||||
<Folder name="typescript - TypeScript config" />
|
||||
</Folder>
|
||||
</Files>
|
||||
|
||||
## Web application structure
|
||||
|
||||
The web application is located in the `apps/web` folder. It contains the following folders:
|
||||
|
||||
<Files>
|
||||
<Folder name="public - Static assets" />
|
||||
|
||||
<Folder name="src" defaultOpen>
|
||||
<Folder name="app - Main application" />
|
||||
|
||||
<Folder name="assets - Optimized static assets" />
|
||||
|
||||
<Folder name="config - Global app config" />
|
||||
|
||||
<Folder name="modules - Application modules" />
|
||||
|
||||
<Folder name="lib - Communication with third-party packages" />
|
||||
|
||||
<Folder name="utils - Shared utilities" />
|
||||
</Folder>
|
||||
|
||||
<File name=".env.local" />
|
||||
|
||||
<File name="env.config.ts" />
|
||||
|
||||
<File name="eslint.config.js" />
|
||||
|
||||
<File name="next.config.ts" />
|
||||
|
||||
<File name="package.json" />
|
||||
|
||||
<File name="tsconfig.json" />
|
||||
|
||||
<File name="turbo.json" />
|
||||
</Files>
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: Updating codebase
|
||||
description: Learn how to update your codebase to the latest version.
|
||||
url: /docs/web/installation/update
|
||||
---
|
||||
|
||||
# Updating codebase
|
||||
|
||||
If you've been following along with our previous guides, you should already have a Git repository set up for your project, with an `upstream` remote pointing to the original repository.
|
||||
|
||||
Updating your project involves fetching the latest changes from the `upstream` remote and merging them into your project. Let's dive into the steps!
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Stash changes
|
||||
|
||||
<Callout title="Don't have changes?">
|
||||
If you don't have any changes to stash, you can skip this step and proceed with the update process.
|
||||
|
||||
Alternatively, you can [commit](https://git-scm.com/docs/git-commit) your changes.
|
||||
</Callout>
|
||||
|
||||
If you have any uncommitted changes, stash them before proceeding. It will allow you to avoid any conflicts that may arise during the update process.
|
||||
|
||||
```bash
|
||||
git stash
|
||||
```
|
||||
|
||||
This command will save your changes in a temporary location, allowing you to retrieve them later. Once you're done updating, you can apply the stash to your working directory.
|
||||
|
||||
```bash
|
||||
git stash apply
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Pull changes
|
||||
|
||||
Pull the latest changes from the `upstream` remote.
|
||||
|
||||
```bash
|
||||
git pull upstream main
|
||||
```
|
||||
|
||||
When prompted the first time, please opt for merging instead of rebasing.
|
||||
|
||||
Don't forget to run `pnpm i` in case there are any updates in the dependencies.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Resolve conflicts
|
||||
|
||||
If there are any conflicts during the merge, Git will notify you. You can resolve them by opening the conflicting files in your code editor and making the necessary changes.
|
||||
|
||||
<Callout title="Conflicts in pnpm-lock.yaml?">
|
||||
If you find conflicts in the `pnpm-lock.yaml file`, accept either of the two changes (avoid manual edits), then run:
|
||||
|
||||
```bash
|
||||
pnpm i
|
||||
```
|
||||
|
||||
Your lock file will now reflect both your changes and the updates from the upstream repository.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Run a health check
|
||||
|
||||
After resolving the conflicts, it's time to test your project to ensure everything is working as expected. Run your project locally and navigate through the various features to verify that everything is functioning correctly.
|
||||
|
||||
For a quick health check, you can run:
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
|
||||
```
|
||||
|
||||
If everything looks good, you're all set! Your project is now up to date with the latest changes from the `upstream` repository.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Commit and push
|
||||
|
||||
Once everything is working fine, don't forget to commit your changes using:
|
||||
|
||||
```bash
|
||||
git commit -m "<your-commit-message>"
|
||||
```
|
||||
|
||||
and push them to your remote repository with:
|
||||
|
||||
```bash
|
||||
git push origin <your-branch-name>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
Reference in New Issue
Block a user