Development setup

​

Before you start

• Node.js 24. The version is pinned in .nvmrc and the root engines field, so nvm use or fnm use picks it up.
• pnpm 12. The root packageManager field pins the exact version (currently [email protected]), and pnpm switches to it automatically when you run it inside the repository.
• Docker with Docker Compose for PostgreSQL, Redis, and S3-compatible storage. Start the Docker daemon first.
• Git.

​

Set up your checkout

git clone https://github.com/reactive-resume/reactive-resume.git
cd reactive-resume

pnpm install --frozen-lockfile

docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket
docker compose -f compose.dev.yml ps

test -e .env.local || cp .env.example .env.local

APP_URL=http://localhost:3000
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
S3_ENDPOINT=http://localhost:8333
REDIS_URL=redis://localhost:6379

openssl rand -hex 32   # paste the output into AUTH_SECRET
openssl rand -hex 32   # paste the output into ENCRYPTION_SECRET

pnpm dev

​

What pnpm dev runs

​

Everyday commands

pnpm --filter web typecheck
pnpm --filter @reactive-resume/pdf test
pnpm exec oxlint --deny-warnings apps/web/src/features/resume
pnpm exec oxfmt --check apps/web/src/features/resume

​

Work with the database

1. Edit the tables in packages/db/src/schema/*.
2. Run pnpm db:generate. The migration is written to the root migrations/ folder.
3. Read the generated SQL, then apply it with pnpm db:migrate or by restarting pnpm dev.

​

Run tests

​

Unit and integration tests

# One package
pnpm --filter @reactive-resume/pdf test

# One file (the path is relative to the package)
pnpm --filter @reactive-resume/pdf test src/templates/shared/filtering.test.ts

# One test by name
pnpm --filter @reactive-resume/pdf exec vitest run src/templates/shared/filtering.test.ts -t "filterItems"

# Coverage (V8, written to the package's coverage/ folder)
pnpm --filter @reactive-resume/pdf test:coverage

​

Browser tests

pnpm exec playwright install chromium

export APP_URL=http://localhost:3000 PORT=3000
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
export AUTH_SECRET=$(openssl rand -hex 32) ENCRYPTION_SECRET=$(openssl rand -hex 32)
export LOCAL_STORAGE_PATH="$PWD/data/e2e"
export FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true
export FLAG_ALLOW_UNSAFE_AI_BASE_URL=true   # lets the assistant spec reach its local stub

pnpm db:migrate
pnpm build
pnpm test:e2e                                  # all specs
pnpm test:e2e tests/e2e/specs/auth.spec.ts     # one spec
pnpm test:e2e:ui                               # Playwright's interactive UI

​

Add translatable text

import { t } from "@lingui/core/macro";
import { Trans } from "@lingui/react/macro";

const label = t`Download PDF`;

<Trans>Your resume is ready.</Trans>;

​

Code style

• TypeScript is strict, including exactOptionalPropertyTypes and noUncheckedIndexedAccess. Packages type-check with tsgo --noEmit.
• Oxlint checks code, including native React Compiler and accessibility rules. Oxfmt formats with tabs, double quotes, and 120-column lines. It sorts imports into type, Node, test, external, workspace, and local groups, and sorts Tailwind classes in clsx, cva, and cn. Side-effect imports retain their order. Install the recommended Oxc editor extension for fixes and formatting on save.
• Configure lint rules in .oxlintrc.json and formatting in .oxfmtrc.json. Generated files and byte-sensitive CSS fixtures stay excluded. Async test doubles are exempt from require-await; source functions still require it. The Playwright fixture adapter is exempt from rules-of-hooks because its use callback belongs to Playwright. CSS declarations are formatted, but Oxlint does not lint them.
• @shadcn/lint is registered with Oxlint. Design-system rules are opt-in; add your chosen rules in .oxlintrc.json, scoped to apps/web and packages/ui. Existing components.json files identify the shared component exports and Tailwind theme. See its rules and configuration examples.
• Coding agents should run pnpm exec oxlint --fix <changed paths>, then pnpm exec oxfmt <changed paths>, and finish with pnpm lint:agent and pnpm format:check. Follow the Oxc coding-agent workflow; fix findings and give any necessary inline suppression a rule-specific explanation.
• React components with explicit props use a named props type, such as type FooProps = {...} with function Foo(props: FooProps).

​

Commits and pull requests

• Before each commit, Lefthook checks staged files for merge conflict markers, applies safe Oxlint fixes, runs Oxfmt, then checks remaining lint findings with warnings denied and stages the fixes.
• On each commit message, commitlint enforces Conventional Commits, such as fix(pdf): keep the timeline dot round or docs: update the development guide.

1. Run the type checks and tests for the packages you changed, plus pnpm lint and pnpm format:check.
2. Run pnpm exec turbo boundaries if you changed imports, exports, or shared contracts.
3. Run pnpm build if you changed runtime or bundling behavior.
4. Keep the pull request focused. Describe the problem, the new behavior, and the checks you ran, and link the related GitHub issue.

​

Troubleshooting

docker compose -f compose.dev.yml logs seaweedfs seaweedfs_create_bucket

​

Next steps