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

# Local development

> Run the web app, the API and the database on your own computer.

## What you need

* [Bun](https://bun.sh) 1.3.14
* Node 20 or later
* Postgres 17, running locally
* The AWS CLI and Terraform 1.12, only for infrastructure work

## First run

**1. Install**

```bash theme={null}
bun install
```

**2. Create the database**

```bash theme={null}
createdb oncoeverything_dev
```

**3. Set the API's environment**

Create `apps/api/.env.local`:

```bash theme={null}
DATABASE_URL="postgres://<you>@localhost:5432/oncoeverything_dev"
```

Leave `MAIL_FROM` unset. The API then prints each email to its console instead of sending it.

**4. Migrate and seed**

```bash theme={null}
bun run --cwd packages/db db:migrate
bun run --cwd apps/api seed-terms
bun run --cwd apps/api seed-sample-reports
bun run --cwd apps/api create-owner -- --email you@example.com --name "Your Name"
```

**5. Start everything**

```bash theme={null}
bun run dev
```

The site is on [localhost:3000](http://localhost:3000) and the API on port 3001.

`create-owner` prints a password once. You can also click **Send me a link instead** on the sign-in page. Then copy the link from the API's console output.

## Commands

| Command | What it does |
| - | - |
| `bun run dev` | Web app and API with hot reload |
| `bun run build` | Builds every package |
| `bun run typecheck` | TypeScript checks |
| `bun run lint` | ESLint, no warnings allowed |
| `bun run test` | Every test suite |
| `bun run format` | Prettier |
| `bun run handbook:screenshots` | Captures the admin screens for this handbook |

Add a shadcn component to the design system:

```bash theme={null}
bunx --bun shadcn@latest add <component> -c apps/web
```

The command adds the component to `packages/ui/src/components`. Import it as `@workspace/ui/components/<component>`.

## Conventions

* **Next.js 16.** Its APIs differ from older versions. Read `node_modules/next/dist/docs/` before you write framework code.
* **Prettier.** No semicolons, double quotes, two spaces, 80 columns, Tailwind classes sorted.
* **Brand rules.** "Oncology" and "Biotech" always take a capital letter. Every Onco-prefixed name carries ™. The rules are in `CLAUDE.md` at the repository root.
* **Copy.** Plain words. A button says what happens. No sales language in the admin.

## The handbook

The handbook is in `handbook/`. To preview it:

```bash theme={null}
cd handbook
npx mint dev
```

Before you push, check the links:

```bash theme={null}
npx mint broken-links
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.