# template-react

A starting point for an app. **Bun · Hono · React 19 SPA · Tailwind v4 · shadcn/ui · Postgres with
Drizzle.** A JSON API at `/api` and a React app at `/`, over one query layer.

## 1. Make it yours

Everything project-specific is called `app`. Rename it once, before the first commit:

| Find | Replace with | Where |
|---|---|---|
| `APP_ENV` | `MYPROJECT_ENV` | `src/env-file.ts`, `package.json` scripts, `test-setup.ts`, `src/databases/app_db/src/env.ts` |
| `appEnv` | `myprojectEnv` | `src/env-file.ts` and its importers |
| `appdb` / `app_db` | `myprojectdb` / `myproject_db` | `src/databases/`, `tsconfig.json` paths, `package.json` scripts |
| `app` / `app_dev` (database names) | `myproject` / `myproject_dev` | `src/databases/app_db/src/env.ts`, `.env.example` |
| `"name": "app"` | your package name | `package.json` |
| `App` | your brand | `src/apps/frontend/App.tsx`, `index.html` `<title>` |
| `3000` | a port of your own | `.env.example`, `src/server.ts` |

A case-sensitive search for `app`, `App` and `APP` finds all of it. Thirty seconds now, a chore later.

## 2. Setup

```bash
bun install
cp .env.example .env               # BUN_PORT, PUBLIC_URL, POSTGRES_URL_DEV
createdb app && createdb app_dev   # or however you make databases
bun run db:push                    # applies the schema — no tables yet, by design
bun dev
```

## Scripts

```bash
bun dev             # development on app_dev, with HMR
bun start           # production on app
bun test
bun run build       # bundle the SPA to dist/
bun run gen:index   # index.gen.html from index.html — also run by predev/prestart/prebuild
bun run db:push     # schema -> app_dev; APP_ENV=production bun run db:push for production
```

## What is served

| Path | |
|---|---|
| `/` and every unmatched path | the SPA — `src/apps/frontend` |
| `/api/*` | the JSON API — `src/servers/api` |
| everything in `public/` | from the root |

## Configuration, and the rules behind it

**`APP_ENV`, never `NODE_ENV`.** It must be `production` or `development` and throws when unset.
Some hosts export `NODE_ENV=production` into every process they spawn, so anything keyed on it
silently treats development as production.

**`NODE_ENV` is still set by both scripts, and must stay explicit.** React resolves its runtime
against it: Bun's bundler emits `jsxDEV()` calls in development, and React's *production*
`jsx-dev-runtime` defines `jsxDEV` as `void 0`. Inherit production while transforming for development
and the app dies with "jsxDEV is not a function".

**Env files are read with the ambient environment last:** `.env.production.local` (production only)
→ `.env.local` → `.env` → `process.env`.

**The database follows from `APP_ENV`** and is enforced before a connection opens; tests cannot reach
production data.

**`PUBLIC_URL`** is substituted into `index.html` by `scripts/gen-index.ts` because Bun's HTML bundler
fails the build on a root-relative favicon `href`. It must be the public origin in production.

## The placeholder

`src/apps/frontend/App.tsx` is a shell with one tab and no features. Add the first screen as a feature
folder — `CONVENTIONS.md` describes the shape. The database has **no tables**; `docs/DATABASE.md`
describes adding the first.

## Documentation

| | |
|---|---|
| `CLAUDE.md` | The rules an agent needs before touching anything |
| `CONVENTIONS.md` | React patterns — feature folders, manager hooks — and the project layout |
| `docs/DATABASE.md` | Drizzle structure, `push` not migrations, `check()` vs open `text` |
| `docs/SURFACES.md` | The API and the app over one query layer |