Development setup

This guide takes you from a fresh clone to a running local copy of Reactive Resume, then covers the commands you’ll use while working on it. For how the code is organized, read Project architecture.

Before you start#

You need:

• 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 pnpm@12.11.2), 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#

Run every command from the repository root unless a step says otherwise.

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

pnpm install --frozen-lockfile

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

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

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

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

pnpm dev

What pnpm dev runs#

pnpm dev loads .env.local through dotenvx and starts three processes with Turborepo:

Use pnpm dev:web to start only Vite. API calls still need a server running.

Everyday commands#

Vite+ supplies the project-local vp CLI for Vite builds/dev servers, Vitest tests, Oxlint, and Oxfmt. Run it with pnpm exec vp; no global install is needed. Turbo still schedules workspace tasks and checks package boundaries, while tsdown packages the server and DeepSeek plugin. Root vite.config.ts owns lint and formatting settings; package vitest.config.ts files retain isolated test configuration.

Keep the pinned vite-plus catalog version and vite override together. The vitest override and @vitest/coverage-v8 must match Vite+‘s bundled Vitest version (pnpm exec vp toolchain vitest). The Vite Plus extension pack uses the same tools and root config as scripts and hooks.

Typechecks use tsrs, an experimental Rust port of TypeScript. The pinned release supports macOS arm64 and Linux x64/arm64 (GNU/musl); Windows and Intel macOS binaries are not published. Existing tsconfig.json strictness settings and --noEmit remain in force. TypeScript stays installed for tools that consume its API and for editors; this migration does not switch editor language servers.

Prefer package-scoped commands while you work. Package names come from each package.json: the apps are web and server, and shared packages are @reactive-resume/<name>.

pnpm --filter web typecheckpnpm --filter @reactive-resume/pdf testpnpm exec vp lint --deny-warnings apps/web/src/features/resumepnpm exec vp fmt --check apps/web/src/features/resume

Work with the database#

All three load .env.local before calling Drizzle Kit, which doesn’t read .env files by itself.

To change the schema:

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#

Tests run through vp test using Vitest and sit next to the code they cover as *.test.ts(x) or *.spec.ts(x). Import test APIs from vite-plus/test. Most packages run in Node; packages/ui uses happy-dom.

PDF export text tests require Poppler’s pdftotext to read logical Unicode text, including /ActualText spans for shaped scripts and emoji. Install it with brew install poppler on macOS or sudo apt-get install poppler-utils on Debian/Ubuntu. CI installs it before running the unit suites.

# One packagepnpm --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 namepnpm --filter @reactive-resume/pdf exec vp test 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

Pass file paths straight after test. An extra -- stops Vitest from filtering the run. Most test scripts use --passWithNoTests, so a green run with zero tests proves nothing about your change.

Database integration suites need COVER_LETTER_TEST_DATABASE_URL, INTEGRATIONS_TEST_DATABASE_URL, and OAUTH_TEST_DATABASE_URL. The migration suite uses COVER_LETTER_TEST_DATABASE_URL as an administrative connection and creates and deletes its own disposable databases, so its user needs CREATE DATABASE permission. Give the OAuth suite its own database, because it writes signing keys. Never point test variables at a database with real data. .github/workflows/ci.yml shows the full setup.

Browser tests#

End-to-end tests use Playwright and live in tests/e2e/specs, with fixtures in tests/e2e/fixtures. They cover sign-up and sign-in, section editing and autosave, JSON export and import, public sharing with statistics and passwords, OAuth consent for MCP clients, and the assistant against a scripted AI provider.

Playwright starts the built server (node apps/server/dist/index.mjs) in production mode and waits for /api/health, so build first. Use a disposable database, and export the variables yourself; these scripts don’t load .env.local.

pnpm exec playwright install chromiumexport APP_URL=http://localhost:3000 PORT=3000export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgresexport 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=trueexport FLAG_ALLOW_UNSAFE_AI_BASE_URL=true   # lets the assistant spec reach its local stubpnpm db:migratepnpm buildpnpm test:e2e                                  # all specspnpm test:e2e tests/e2e/specs/auth.spec.ts     # one specpnpm test:e2e:ui                               # Playwright's interactive UI

Without FLAG_ALLOW_UNSAFE_AI_BASE_URL=true, the assistant spec skips itself. Playwright runs Chromium with no retries. Locally it reuses a server that’s already running on PORT. See tests/e2e/README.md for the full recipe.

Add translatable text#

The web app uses Lingui. Wrap every user-facing string in a macro:

import { t } from "@lingui/core/macro";import { Trans } from "@lingui/react/macro";const label = t`Download PDF`;<Trans>Your resume is ready.</Trans>;

Then run pnpm lingui:extract. It updates the catalogs in apps/web/locales/*.po and regenerates the PDF section-title catalog. You only add English strings; translators handle the rest on Crowdin. See Contributing translations.

Code style#

• TypeScript is strict, including exactOptionalPropertyTypes and noUncheckedIndexedAccess. Packages type-check with tsrs --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 the root vite.config.ts lint block and formatting in its fmt block. 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 the root vite.config.ts lint block, 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.
• React components with explicit props use a named props type, such as type FooProps = {...} with function Foo(props: FooProps).

Commits and pull requests#

The Git hooks run automatically:

• 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.

Before you open a pull request:

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.

Pull requests run the CI workflow (.github/workflows/ci.yml) with four parallel checks:

The separate autofix.ci workflow (autofix.yml) runs pnpm knip --fix and pnpm check, then pushes any fixes to your branch. The autofix.ci service requires its own workflow name.

New commits to a pull request cancel its superseded CI and autofix runs. Docker publishing and mobile release workflows run separately.

Keep credentials and personal resume data out of code, logs, test fixtures, issues, and pull requests.

Troubleshooting#

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

Next steps#