Set up a development environment

Go from a fresh clone to Monark running on your machine, with the tests passing and a change of your own visible in the browser. This is for developers who want to work on Monark itself. It takes about 20 minutes, most of it downloads.

Before you start

Node 22 or later. The repository's .nvmrc pins 22, so nvm use picks it up.
pnpm 10, through Corepack: run corepack enable once.
Docker (Docker Desktop, OrbStack or colima), running. The local Supabase stack and the integration tests use it.
Git and a clone of the repository.

You don't need to install the Supabase CLI; it comes with the project's dependencies.

Install and configure

In the repository root, select the Node version and run the bootstrap:
```
nvm use
pnpm bootstrap
```
Wait for it to finish. It checks your tools, copies every .env.example to .env, installs dependencies, starts the local Supabase stack, fills in the local database URLs, keys and secrets, and applies the database migrations.

Bootstrap never overwrites a value you've already set, so it's safe to run again. It leaves real outside services blank on purpose: SMTP, Sentry and your branding. Without SMTP, outgoing mail goes to the local mail catcher instead.

Start the app

Start the web app and the api:
```
pnpm dev
```
Open http://localhost:3000. You see the sign-in page. The api runs on http://localhost:4000.

If the api logs Can't reach database server at localhost:54322, the Supabase stack is down; start it with pnpm exec supabase start and run pnpm dev again.

Create your account

On the sign-in page, click Create one, enter an email and a password, and click Create account.
Open the local mail catcher with pnpm dev:tools:mail (or go to http://localhost:54324), open the confirmation email, and click its link. You land in the app, already a member of the local organization.
Make yourself a system administrator so you can reach every admin screen:
```
pnpm sysadmin grant you@example.com
```
Turn on the features that are off by default, such as the wiki, the assistant and the public API:
```
pnpm enable:dev-flags
```
Reload the page. Admin and the extra areas now appear in the navigation.

Run the tests

Run the unit and component tests. They need nothing running:
```
pnpm test
```
Run one package's integration tests. Each run starts a throwaway Postgres container in Docker, so it never touches your development database:
```
pnpm --filter @monark/calendar test:integration
```

Both finish with every test passing. pnpm test:integration runs every package's suite, one package at a time; it takes several minutes.

Make a change

Open services/web/src/messages/en.json and find "signIn", under "auth".
Change "title": "Welcome back" to "title": "Welcome back, developer" and save.
Sign out from the user menu (Logout). The sign-in page shows your new heading without a restart.
Undo the change. Every visible string has to exist in both en.json and fr.json, and pnpm check:i18n fails otherwise.

What you built

You have Monark running against a local Supabase stack, an account with full access, the tests passing, and the edit-reload loop working. Before you open a pull request, run the same checks CI runs; Scripts lists them.

Next, pick the job you came for in Build on Monark: add a module, change the database schema, or write tests. For how the pieces fit, read Architecture.