> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxresu.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Set up a local development environment for Reactive Resume

<Info>
  **Prerequisites**: - [Node.js](https://nodejs.org/) v24 - [pnpm](https://pnpm.io/) v11.1.2 through Corepack -
  [Docker](https://docs.docker.com/get-docker/) and Docker Compose - [Git](https://git-scm.com/)
</Info>

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

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/amruthpillai/reactive-resume.git
    cd reactive-resume
    ```
  </Step>

  <Step title="Install Dependencies">
    This project uses [pnpm](https://pnpm.io/) through Corepack.

    ```bash theme={null}
    # Enable the package manager version from package.json
    corepack enable

    # Install project dependencies
    pnpm install
    ```
  </Step>

  <Step title="Start Infrastructure Services">
    If you want to run the app directly on your machine with `pnpm dev`, start only the infrastructure services:

    ```bash theme={null}
    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)

    <Info>
      **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.
    </Info>

    <Tip>
      `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.
    </Tip>

    <Tip>
      Wait for all services to be healthy before proceeding. Check with `docker compose -f compose.dev.yml ps`.
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the project root:

    ```bash theme={null}
    # 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 <noreply@rxresu.me>"

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

    <Tip>
      **Email Testing**: The development stack includes [Mailpit](https://mailpit.axllent.org/), an email testing tool. All emails sent by the application will be captured and viewable at [http://localhost:8025](http://localhost:8025). No emails will actually be sent to real addresses during development.
    </Tip>
  </Step>

  <Step title="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`:

    ```bash theme={null}
    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm run db:migrate
    ```
  </Step>

  <Step title="Start the Development Server">
    ```bash theme={null}
    pnpm run dev
    ```

    Your local Reactive Resume instance will be available at [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

***

## 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:

```bash theme={null}
pnpm run db:studio
```

This opens a web-based GUI at [https://local.drizzle.studio](https://local.drizzle.studio).

### Making Schema Changes

1. Edit the schema in `packages/db/src/schema/*`
2. Generate a migration:
   ```bash theme={null}
   pnpm run db:generate
   ```
3. Apply the migration:
   ```bash theme={null}
   pnpm run db:migrate
   ```

<Warning>Always review generated migrations before applying them, especially when working with existing data.</Warning>

***

## Working with Translations

Reactive Resume uses [Lingui](https://lingui.dev/) for internationalization.

### Adding Translatable Text

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

```tsx theme={null}
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:

```bash theme={null}
pnpm run lingui:extract
```

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

***

## Code Quality

### Linting & Formatting

Uses [Biome](https://biomejs.dev/) for linting, formatting, import organization, and Tailwind class sorting:

```bash theme={null}
# Non-mutating check
pnpm exec biome check .

# Project script with write/fix behavior
pnpm check
```

### Type Checking

Run TypeScript type checking:

```bash theme={null}
pnpm run typecheck
```

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

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 `
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 `
  </Accordion>

  <Accordion title="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 `
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Project Architecture" icon="folder-open" href="/contributing/architecture">
    Deep dive into the project architecture and codebase structure.
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/amruthpillai/reactive-resume">
    View the source code and contribute to the project.
  </Card>
</CardGroup>