Environment Setup

A practical checklist from a fresh clone to a running local stack. See Our Stack for what each piece is and why.

Prerequisites#

Node >=20 (package.json engines)
pnpm 9.14.2: pinned in the root package.json’s packageManager field. If you use Corepack, corepack enable picks this exact version up for you.
A local PostgreSQL instance: apps/api and apps/lore-api each need one to migrate against.

Clone and install#

pnpm install

One install covers every app and package in the workspace. It also runs husky’s prepare step, which wires up the pre-commit hook: eslint --fix + prettier on staged .ts/.tsx, prettier on staged .astro/.json/.md/.css/.yml.

The layout#

Two top-level folders, declared in pnpm-workspace.yaml:

Folder	Contains
`apps/*`	Deployable applications: `api`, `web`, `landing`, `lore-api`, `lore-web`, `glide-mcp`
`packages/*`	Shared code, not shipped on its own: `domain`, `shared`, `editor`, `ui`, `pgmq`

turbo.json defines the tasks (build, dev, lint, typecheck, test) that run across whichever of these a change touches, reusing the cache between them.

Environment variables#

Each app that needs configuration ships an .env.example: apps/api/.env.example, apps/web/.env.example, apps/lore-api/.env.example. Copy the one for the app you’re touching to .env and fill in your own local values (a local DATABASE_URL, a generated BETTER_AUTH_SECRET, and so on). Never commit a real .env, and never put a real secret in this repo’s docs.

Where the real values for shared, staging, and production environments come from, and how they’re classified and handled, is covered in Security & Data Handling; this page only covers getting your own machine running.

Database#

apps/api and apps/lore-api each own their schema and migrations. Once DATABASE_URL is set in your .env:

pnpm --filter @systeric/api db:migrate

runs the pending migrations for that app. See Database Migrations for the full model: schema lives in apps/api/src/db/schema/, migrations in apps/api/drizzle/, and they are forward-only.

Running it#

Everything at once: pnpm dev from the root (turbo run dev) starts every app’s dev server together.
One app at a time: pnpm --filter @systeric/web dev (swap in @systeric/api, @systeric/landing, etc.).

Before you open a PR, run what CI runs: pnpm test, pnpm run lint, pnpm run typecheck, pnpm build. See Testing & TDD for what each of those checks and why green is the floor, not a bonus.