arcstack

A minimal Bun monorepo template using built-in workspaces — no Turborepo or other build orchestration. Next.js on the front, Hono on the back, shadcn in between, and one place to pin shared versions.

Structure

apps/
  client/  → @apps/client   Next.js 16 + Turbopack        :1001
  server/  → @apps/server   Hono on Bun.serve()           :1002
packages/
  shared/  → @arc/shared    shared utilities and types
  ui/      → @arc/ui        shadcn components, providers, styles

apps/* are deployable. packages/* are libraries, and the only workspaces bun run test covers.

Getting started

bun install
cp .env.example .env
bun run dev          # every app in watch mode, in parallel

Scripts

Command	Description
bun run dev	Run every app in watch mode
bun run build	Build every app
bun run start	Run every app in production mode
bun run typecheck	Type-check every workspace
bun run lint	Lint and format-check with Biome
bun run lint:fix	Apply every safe Biome fix
bun run test	Run packages/* tests with bun test

Anything workspace-specific goes through the filter:

bun run --filter @apps/client dev
bun run --filter @arc/ui add button      # add a shadcn component

Dependencies

Versions shared by more than one workspace are pinned once in the root catalog, so a bump happens in a single place:

// package.json
"catalog": { "hono": "^4", "next": "^16.2.12" }

// apps/server/package.json
"dependencies": { "hono": "catalog:" }

A package used by exactly one workspace is pinned in that workspace instead.

bun add -d <package>                      # root, dev tooling only
bun add --filter @apps/server <package>   # a single workspace

Conventions

• Bun APIs only — no Node or npm equivalents. CLAUDE.md has the full list.
• Tests sit beside their source as *.test.ts and run under bun test.
• Linting and formatting via Biome: tabs, double quotes.
• Path aliases @arc/* and @apps/* resolve through the root tsconfig.json. packages/ui and the Next apps override lib/jsx on purpose; see CLAUDE.md before changing either.
• packages/ui/src/components/ is generated by shadcn add. Biome's a11y rules are off there because the files are overwritten on regeneration.

Adding a service

services/* is deliberately absent. If a long-running worker needs its own deployable, create services/<name>, add "services/*" to workspaces, and widen the dev/build/start filters to --filter '@apps/*' --filter '@services/*'.