# CMS Monorepo (Bun + Biome + Next.js)

Roadmap and progress are tracked in `TODO.md` (also visible in admin at `/todo`).

A baseline monorepo with:

- `apps/web`: public frontend app
- `apps/admin`: separated admin app
- `packages/ui`: shared UI primitives (shadcn-ready)
- `packages/content`: shared Zod schemas/types
- `packages/db`: Prisma + PostgreSQL data access
- `packages/config`: shared TypeScript config

## Stack

- Bun workspaces
- Biome (lint + format)
- Next.js App Router + TypeScript + `src/`
- Tailwind CSS
- Prisma + PostgreSQL
- Zod
- Zustand
- TanStack (Query, Table, Form)

## Quick start

1. Install dependencies:

```bash
bun install
```

2. Copy env and set your database URL:

```bash
cp .env.example .env
```

3. Generate Prisma client and run migrations:

```bash
bun run db:generate
bun run db:migrate
bun run db:seed
```

4. Run both apps:

```bash
bun run dev
```

- Web: http://localhost:3000
- Admin: http://localhost:3001

## Useful scripts

- `bun run dev`
- `bun run dev:web`
- `bun run dev:admin`
- `bun run test`
- `bun run test:watch`
- `bun run test:coverage`
- `bun run test:e2e`
- `bun run lint`
- `bun run typecheck`
- `bun run check`
- `bun run format`
- `bun run db:generate`
- `bun run db:migrate`
- `bun run db:push`
- `bun run db:studio`
- `bun run db:seed`

## Testing

- Unit/integration/component: Vitest + Testing Library + MSW
- E2E: Playwright (separate projects for `web` and `admin`)
- Use `bun run test` and `bun run test:e2e` (not plain `bun test`, which uses Bun's runner)

One-time Playwright browser install:

```bash
bunx playwright install
```

## Delivery Scaffolding

The repo includes a theoretical CI/CD and deployment baseline:

- Gitea workflow: `.gitea/workflows/ci-cd-theoretical.yml`
- App images:
  - `apps/web/Dockerfile`
  - `apps/admin/Dockerfile`
- Runtime stacks:
  - `docker-compose.staging.yml`
  - `docker-compose.production.yml`

Compose helper scripts:

- `bun run docker:staging:up`
- `bun run docker:staging:down`
- `bun run docker:production:up`
- `bun run docker:production:down`

Environment examples:

- `.env.staging.example`
- `.env.production.example`

Notes:

- `dev` remains your local non-docker Bun workflow.
- Staging and production compose files are templates and still require real secrets, registry strategy, and deployment host wiring.

## Recommended next packages

- Auth: `better-auth` or `next-auth`
- Uploads: `uploadthing`
- Rich text: `@tiptap/react`
- Caching/queue: `bullmq`, `ioredis`
- Email: `resend`
- i18n: `next-intl`
- Observability: `@sentry/nextjs`
- Testing: `vitest`, `@testing-library/react`, `playwright`

For TanStack specifically, this baseline already includes Query, Table, and Form. Add Virtual when you introduce very large lists:

- `@tanstack/react-virtual`