CMS Monorepo (Bun + Biome + Next.js)

Roadmap and progress are tracked in TODO.md (also visible in admin at /todo). Branch model and promotion flow are documented in BRANCHING.md. Commit schema and changelog workflow are documented in CONTRIBUTING.md.

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:

bun install

2. Copy env and set your database URL:

cp .env.example .env

3. Generate Prisma client and run migrations:

bun run db:generate
bun run db:migrate
bun run db:seed

4. Run both apps:

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 docs:dev
• bun run docs:build
• bun run docs:preview
• 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:

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.

Changelog

• Changelog file: CHANGELOG.md
• Commit schema: Conventional Commits (see CONTRIBUTING.md)
• Generate/update changelog from git commits:

bun run changelog:release

• Preview generated output without writing file:

bun run changelog:preview

Docs Tool

• Docs tool: VitePress
• Docs source directory: docs/

Run docs locally:

bun run docs:dev

Build static docs:

bun run docs:build

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