Getting started

This page takes you from a clone to a running workspace.

If you use GitHub Codespaces, the devcontainer installs Node.js, pnpm, and MySQL 8.0. It also installs the workspace dependencies and runs pnpm dev:setup to prepare the database and development accounts. Skip the install and setup commands below, then start the workspace with pnpm dev.

Install the tools

Install these tools:

• Git
• Node.js 24.21.0
• pnpm 12
• MySQL 8.0 or 8.4, for the MySQL integration tests. On macOS, run brew install mysql@8.4 and brew services start mysql@8.4.

The packageManager field in package.json pins the exact pnpm version. .devcontainer/devcontainer.json installs the same Node.js and pnpm versions.

Install the repository

Clone the repository, then install the workspace dependencies:

git clone <repository-url> concourse
cd concourse
pnpm install

The install command patches the workspace TypeScript and Oxlint binaries for Effect. The pinned versions are in pnpm-workspace.yaml. Keep them compatible with @effect/tsgo.

Set up VS Code

Open the repository root in VS Code. Install the recommended OXC, TypeScript 7, and Effect Dev Tools extensions. Open a TypeScript file. The workspace settings point TypeScript 7 at the patched workspace language server. Select Allow when TypeScript 7 asks to use the workspace SDK.

To check the setup, create a temporary TypeScript file in an Effect-owned package:

import { Effect } from "effect";

Effect.log("Check the Effect language service");

The language server reports the unused Effect and offers an Effect fix. Remove the temporary file after the check. pnpm check checks Effect-owned files through Oxlint. Every workspace check fails on lint warnings. Oxlint supplies the Effect gate for dedicated and mixed projects. Retained compiler tasks cover files and configurations that Oxlint does not select. React, Next.js, and Promise SDK code can use ordinary TypeScript control flow. The Effect boundary standard identifies each scope. The toolchain decision records the version constraint. VS Code can show duplicate findings in strict Effect projects.

The Effect Dev Tools extension also has runtime inspection views. Those views need app instrumentation, which this setup does not add.

Configure the development environment

Each executable owns its environment. Concourse and the CLI commit safe .env.development and .env.test files in their own directories. Next.js loads application files natively; standalone commands load files from their own workspace. Libraries read the active Effect configuration provider. Root aliases use the same workspace commands as direct invocation.

Put personal values in apps/concourse/.env.local, apps/midot/.env.local, or apps/cli/.env.local, according to the consumer. Concourse and CLI defaults target the same local SQLite database and Maildev instance. If you change those resources, update both owners' personal files. There is no hidden synchronization between workspaces.

Supplied process variables win. Next development then prefers .env.development.local, .env.local, .env.development, and .env, in that order. Tests prefer .env.test.local, .env.test, and .env; they exclude development files and .env.local. Keep test overrides restricted to test resources. The CLI uses only .env.local over .env.development for development and .env.test.local over .env.test for test configuration. CLI values are literal; Next files support interpolation. Do not copy production credentials into committed files.

Local development uses file:data/sqlite/concourse.db, relative to the repository root even when a command runs in an app. Tests use separate local SQLite files. Neither needs a Turso account or token. Remote libsql:, https:, and wss: database URLs require TURSO_AUTH_TOKEN. Remote verification remains a separate CI gate. CONCOURSE_WORKSPACE_ROOT is an optional explicit path override; commands normally discover the repository root.

Owner examples list supported settings: Concourse, Midot, and CLI. Effect Config validates settings and keeps secrets redacted. CLI production mode and deployment orchestration load no local files. Explicit NODE_ENV selects the mode; without it, CI defaults to production and local commands default to development. See the accepted environment decision.

When moving an existing root .env.local, copy each value to its actual consumers. Resolve conflicts before replacing values, verify the copies without printing secrets, then remove the original. Keep credentials in ignored personal files.

Prepare the development environment

Run the one-time setup command:

pnpm dev:setup

The command does these steps in order:

1. Create data/sqlite/concourse.db and apply the migrations.
2. Add the development seed data.
3. Create the local administrator and two organization users for impersonation.
4. Load the local Rackspace databases that MIDOT uses with synthetic data. This step needs MySQL.

If one step reports an error, the command stops. Repeat that step with its own command from the command reference.

If db:migrate reports table ... already exists, your local database comes from an earlier migration history. Run pnpm db:reset once, then run pnpm dev:setup again.

The local administrator is admin@concourse.local with the password concourse-local-admin-password. It owns Template Organization. The tracked apps/cli/.env.development file holds these values. Do not use them outside local development.

The users impersonated-admin@concourse.local and impersonated-member@concourse.local have the organization roles admin and member. They have no password. Sign in as the administrator and open /admin to impersonate one of them.

Start the workspace

Start the development processes:

pnpm dev

The command starts every app, Drizzle Studio, and Maildev. Open these services:

Codespaces forwards the ports that .devcontainer/devcontainer.json lists.

Press Ctrl+C once and wait for the apps, Drizzle Studio, and Maildev to stop.

Check a change

Before you submit a change, run the focused checks for the files that you changed. The command reference lists them. If a change crosses several areas, run the complete merge gate:

pnpm verify

Next steps

• Read the command reference.
• Read the database package guide before you change a table or a migration.
• Read the deployment runbook before you change a production or preview setting.