Development Setup

Prerequisites: - Node.js v24 - pnpm v11.1.2 through Corepack - Docker and Docker Compose - Git

This guide walks you through setting up Reactive Resume for local development. Whether you’re contributing to the project or customizing it for your needs, these steps will get you up and running.

Setting Up Your Development Environment

Clone the Repository

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

Install Dependencies

This project uses pnpm through Corepack.

# Enable the package manager version from package.json
corepack enable

# Install project dependencies
pnpm install

Start Infrastructure Services

If you want to run the app directly on your machine with pnpm dev, start only the infrastructure services:

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

This starts the following infrastructure services:

PostgreSQL — Database (port 5432)
Redis — AI Agent workspace streams/state (port 6379)
SeaweedFS — S3-compatible storage (port 8333)

From v5.1.0 onwards — PDF generation now runs entirely in the browser via @react-pdf/renderer, so no Browserless or Chromium container is required for development.

compose.dev.yml can also run the app in a development container with docker compose -f compose.dev.yml up -d. Use the service-filtered command above when you want local editor tooling and pnpm dev on the host.

Wait for all services to be healthy before proceeding. Check with docker compose -f compose.dev.yml ps.

Configure Environment Variables

Create a .env file in the project root:

# Application
PORT=3000
SERVER_PORT=3001
APP_URL=http://localhost:3000

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

# Authentication
AUTH_SECRET=development-secret-change-in-production

# Storage (SeaweedFS)
S3_ACCESS_KEY_ID=seaweedfs
S3_SECRET_ACCESS_KEY=seaweedfs
S3_ENDPOINT=http://localhost:8333
S3_BUCKET=reactive-resume
S3_FORCE_PATH_STYLE=true

# Email (Mailpit for local development)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM="Reactive Resume <[email protected]>"

# AI Agent workspace and saved AI providers
REDIS_URL=redis://localhost:6379
ENCRYPTION_SECRET=change-me-to-a-secure-agent-secret-in-production

Email Testing: The development stack includes Mailpit, an email testing tool. All emails sent by the application will be captured and viewable at http://localhost:8025. No emails will actually be sent to real addresses during development.

Run Database Migrations If Needed

The server startup path runs migrations before serving traffic. To apply migrations manually without starting the app, export DATABASE_URL because Drizzle Kit reads directly from process.env:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm run db:migrate

Start the Development Server

pnpm run dev

Your local Reactive Resume instance will be available at http://localhost:3000.

Available Scripts

Here are the most commonly used scripts during development:

Development

Command	Description
`pnpm dev`	Start the web and server development processes
`pnpm build`	Build the production web bundle and server bundle
`pnpm start`	Start the built production server
`pnpm typecheck`	Run TypeScript type checking
`pnpm test`	Run Vitest across workspaces
`pnpm exec biome check .`	Run a non-mutating Biome check
`pnpm check`	Run Biome with write/fix behavior (`--write --unsafe`)
`pnpm exec turbo boundaries`	Check workspace/package boundary rules

Database

Command	Description
`pnpm run db:generate`	Generate migration files from schema changes
`pnpm run db:migrate`	Apply pending migrations
`pnpm run db:studio`	Open Drizzle Studio (database GUI)

Internationalization

Command	Description
`pnpm run lingui:extract`	Extract translatable strings from code

Understanding the Project Structure

Understanding the project structure will help you navigate the codebase:

reactive-resume/
├── apps/
│   ├── web/                # TanStack Start routes, web features, and browser UI
│   └── server/             # Hono production server, HTTP adapters, static serving
├── packages/
│   ├── api/                # oRPC features and business behavior
│   ├── auth/               # Better Auth configuration and helpers
│   ├── db/                 # Drizzle client and schema
│   ├── docx/               # DOCX export generation
│   ├── mcp/                # MCP tools, prompts, resources, and metadata
│   ├── pdf/                # React PDF rendering and PDF generation adapters
│   ├── resume/             # Pure resume-domain helpers
│   ├── schema/             # Zod schemas and typed models
│   ├── ui/                 # Shared Base UI/shadcn-style primitives
│   └── ...
├── tooling/                # Development-only scripts and repository tooling
├── migrations/             # Generated database migrations
├── docs/                   # Documentation
└── data/                   # Local development data and uploads

Working with the Database

Viewing the Database

Use Drizzle Studio to explore and manage your database:

pnpm run db:studio

This opens a web-based GUI at https://local.drizzle.studio.

Making Schema Changes

Edit the schema in packages/db/src/schema/*
Generate a migration:
pnpm run db:generate
Apply the migration:
pnpm run db:migrate

Always review generated migrations before applying them, especially when working with existing data.

Working with Translations

Reactive Resume uses Lingui for internationalization.

Adding Translatable Text

Use the t macro for strings or <Trans> component for JSX:

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

// For plain strings
const message = t`Hello, World!`;

// For JSX content
<Trans>Welcome to Reactive Resume</Trans>;

Extracting Translations

After adding new translatable text, extract them to the locale files:

pnpm run lingui:extract

Translation files are located in apps/web/locales in .po format.

Code Quality

Linting & Formatting

Uses Biome for linting, formatting, import organization, and Tailwind class sorting:

# Non-mutating check
pnpm exec biome check .

# Project script with write/fix behavior
pnpm check

Type Checking

Run TypeScript type checking:

pnpm run typecheck

Configure your IDE to use Biome for formatting and lint diagnostics. The repo uses tabs, double quotes, 120-column lines, and organized import groups.

Troubleshooting

Port 3000 or 3001 is already in use

The Vite web server uses PORT (default 3000), and the Hono server uses SERVER_PORT (default 3001). Either stop the conflicting process or choose alternate ports: bash PORT=3002 SERVER_PORT=3003 pnpm dev

Database connection refused

Ensure Docker containers are running: bash docker compose -f compose.dev.yml ps docker compose -f compose.dev.yml up -d Check that PostgreSQL is healthy and accessible on port 5432.

S3/Storage errors

Verify SeaweedFS is running and the bucket exists:

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

If the bucket wasn’t created, restart the bucket creation service: bash docker compose -f compose.dev.yml restart seaweedfs_create_bucket

Type errors after pulling changes

The route tree may need regeneration. Run the dev server which auto-generates routes: bash pnpm run dev Or run type checking to see specific errors: bash pnpm run typecheck

Setting Up Your Development Environment

Available Scripts

Development

Database

Internationalization

Understanding the Project Structure

Working with the Database

Viewing the Database

Making Schema Changes

Working with Translations

Adding Translatable Text

Extracting Translations

Code Quality

Linting & Formatting

Type Checking

Troubleshooting

Next Steps

Project Architecture

GitHub Repository

​Setting Up Your Development Environment

​Available Scripts

​Development

​Database

​Internationalization

​Understanding the Project Structure

​Working with the Database

​Viewing the Database

​Making Schema Changes

​Working with Translations

​Adding Translatable Text

​Extracting Translations

​Code Quality

​Linting & Formatting

​Type Checking

​Troubleshooting

​Next Steps

Project Architecture

GitHub Repository

Setting Up Your Development Environment

Available Scripts

Development

Database

Internationalization

Understanding the Project Structure

Working with the Database

Viewing the Database

Making Schema Changes

Working with Translations

Adding Translatable Text

Extracting Translations

Code Quality

Linting & Formatting

Type Checking

Troubleshooting

Next Steps