Skip to main content
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 26. The version is pinned in .nvmrc and the root engines field, so nvm use or fnm use picks it up.
  • pnpm 12. Use the exact version in the root packageManager field. pnpm switches to that version 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.
1

Clone the repository

--filter=blob:none downloads the full commit history but only the current files, which keeps the clone near 130 MB instead of over 2 GB. Git fetches older file versions when a command such as git blame or git checkout needs them.
2

Install dependencies

The install also sets up the Lefthook Git hooks described in Commits and pull requests.
3

Start the infrastructure services

This starts:Wait until ps shows the services as healthy. PDF generation runs on the Forme engine in WebAssembly, so you don’t need a Chromium or Browserless container.
4

Create your environment file

Copy the template only if you don’t have a .env.local yet:
The template uses container hostnames. Because the app runs on your machine, change these values in .env.local to localhost:
Then generate the secrets:
AUTH_SECRET is required. ENCRYPTION_SECRET (at least 32 characters) is needed only for saved AI providers and the assistant, but it’s easiest to set it now. Redis is optional; with it, assistant replies survive a page reload and rate limits are shared between server processes. Every variable is described in Environment variables.
Working on something that doesn’t need uploads? Start only postgres and set STORAGE_BACKEND=local. Files then go to the data/ folder in your checkout.
5

Start the app

Open http://localhost:3000. The server applies database migrations on startup, so a fresh database is ready as soon as the app loads.
6

Create a local account

Select Sign up and create an account. Without SMTP settings, the app doesn’t send email: verification and password-reset links are printed in the terminal running pnpm dev. Copy the link from there into your browser.

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 vp pack (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>.

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.
Review every generated migration before you apply it. Don’t reset the database or delete Docker volumes to work around a setup error; find the cause instead.

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

Some suites run against a real PostgreSQL database and skip themselves when their database variables are missing. With PostgreSQL running from compose.dev.yml, run them through pnpm test:db:
pnpm test:db exec creates two databases named after your checkout directory, applies pending migrations to both, and runs the command with the variables the CI unit job sets: COVER_LETTER_TEST_DATABASE_URL, INTEGRATIONS_TEST_DATABASE_URL, OAUTH_TEST_DATABASE_URL, the fixed test secrets and flags, and REQUIRE_DB_TESTS=1. With REQUIRE_DB_TESTS=1, a missing database variable fails the run instead of skipping the suites, so a green run means they ran. Separate worktrees get separate databases. The commands only manage databases on a local server. Set TEST_DB_ADMIN_URL if yours isn’t at postgresql://postgres:postgres@localhost:5432/postgres; its user needs CREATE DATABASE permission, which the migration suite also uses. To set the variables yourself instead, follow the CI unit job in .github/workflows/ci.yml: give the OAuth suites their own database, because they write signing keys, and never point test variables at a database with real data.

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. With PostgreSQL running from compose.dev.yml, run them with pnpm test:e2e:local:
The command sets up the CI browser job for this checkout: a migrated database named after the checkout directory, local file storage in the system temporary folder, a free port, and the same fixed secrets and flags as CI, including FLAG_ALLOW_UNSAFE_AI_BASE_URL=true for the assistant specs. Playwright starts the built server (node apps/server/dist/index.mjs) in production mode, so pass --build after changing application code; without a build, the command stops and says so. Other arguments go to playwright test. Playwright runs Chromium with no retries. To run Playwright directly, export the CI browser job’s variables against a disposable database, then run pnpm db:migrate, pnpm build, and pnpm test:e2e. These scripts don’t load .env.local. Playwright reuses a server that’s already running on PORT, so pick a port no other checkout uses. See tests/e2e/README.md for details.
Keep the unsafe AI and OAuth redirect flags for isolated test installations. They relax SSRF and redirect protections.

Add translatable text

The web app uses Lingui. Wrap every user-facing string in a macro:
Then run pnpm lingui:extract. It updates the web catalogs in apps/web/locales/*.po, the mobile catalogs in apps/mobile/locales/*.po (seeding empty entries from matching web translations), and regenerates the PDF section-title catalog. Fill and review the affected translations in both apps before release; the repository has no automatic Crowdin synchronization workflow. 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.

Release documentation checklist

Alongside the release’s changelog entry:
  1. Review the screens changed by the release and update their user guides, including control names and navigation.
  2. Re-shoot affected guide screenshots against the release source with fictional people and companies. Inspect each image, then match its caption and alt text to what it actually shows.
  3. Run pnpm docs:check and review its warnings for possible UI-label drift, missing pages or images, broken heading links, and unreferenced images. The check does not verify screenshots or replace a product walkthrough.

Troubleshooting

Stop the other process, or set different values for PORT and SERVER_PORT in .env.local and change APP_URL to match. Keep port 3002 free for the email preview.
Check that the containers are healthy with docker compose -f compose.dev.yml ps. Code on your machine connects to localhost; code inside a container uses the service name, such as postgres.
Read the storage logs:
Check that S3_ENDPOINT is http://localhost:8333 and the bucket exists. If you don’t need S3, set STORAGE_BACKEND=local.
apps/web/src/routeTree.gen.ts is generated. Start pnpm dev (or run pnpm build) to regenerate it, and never edit it by hand.
Saved AI providers and the assistant need ENCRYPTION_SECRET (at least 32 characters). Set it in .env.local and restart pnpm dev.
CommonJS server dependencies must be bundled. Add the package and its dependencies to bundledInteropPackages in apps/server/vite.config.ts. See Deployment checks.

Next steps

Project architecture

Learn where each part of the code lives and where new code belongs.

GitHub repository

Browse the source, open issues, and send pull requests.