TypeScript Bun Starter

Bun-first monorepo starter and scaffold CLI for building CLI, CLI + API, or CLI + API + Web projects with strict TypeScript, shared contracts, and a contract-driven scaffold workflow.

Features

Architecture & Foundation

• Bun-native monorepo — workspaces, bun:test, bun build --compile, no npm/pnpm/yarn
• Three deployable tiers — CLI (tbs), Hono API server, Astro 6 web app — keep what you need, remove the rest via scaffold commands
• Strict TypeScript — strict: true, Zod schemas, compile-time contract alignment between packages
• Shared contracts layer — @starter/contracts owns DTOs, validation, and HTTP transport helpers; all tiers consume it
• Typed RPC client — web tier imports AppType from @starter/api-types for end-to-end type-safe API calls via Hono RPC

Data & Infrastructure

• Drizzle ORM with multi-adapter DB layer — Bun SQLite for local/dev, Cloudflare D1 for production; schema-first migrations with drift detection
• Event bus — typed publish/subscribe with DB-backed observers for cross-concern decoupling
• DB-backed job queue — persistent enqueue/consume with status tracking and queue stats
• Pluggable scheduler — cron jobs via node-cron (Node mode) or Cloudflare Cron Triggers; unified ScheduledJob interface
• Runtime profiles — node-bun and cloudflare-workers profiles with per-runtime modules, system bus factory, and action registry; auto-detected at startup
• Process executor — managed child-process execution with lifecycle hooks

API & Middleware

• Hono API server — modular route architecture with @hono/zod-openapi for schema-driven validation
• Swagger UI — auto-generated interactive API docs
• Middleware stack — API key auth, rate limiting, request ID, CORS, security headers, error handling, observability tracing, DB injection

Observability

• OpenTelemetry built in — tracing, metrics, and span helpers in @starter/core; local Jaeger stack via Docker Compose
• Structured logging — Logtape-based logging with configurable levels and output adapters

Deployment & Cloud

• Cloudflare Workers + Pages — wrangler config, D1 bindings, KV sessions, and cron triggers out of the box
• Standalone CLI binary — bun build --compile produces a single tbs executable with zero runtime deps

Developer Tooling

• Scaffold CLI (tbs) — init, add, remove, validate, and list project profiles
• Policy engine — 13 deterministic policies (naming, import boundaries, no-secrets, logger usage, runtime boundaries, etc.) enforced via bun run check:policy
• Quality gate — bun run check runs format, lint, scaffold validation, docs validation, policy checks, DB drift detection, typecheck, tests, and coverage in one command

Repo Map

packages/contracts/    Shared DTOs, Zod schemas, HTTP transport helpers
packages/core/         DB adapters, Drizzle schema, logging, telemetry, event bus,
                       job queue, scheduler, process executor, API client, config loader
packages/api-types/    Type-only RPC seam — re-exports server AppType for the web tier
apps/cli/              Scaffold CLI built with Commander (compiles to standalone tbs binary)
apps/server/           Hono API with Swagger UI, middleware stack, modular routes, cron scheduler
apps/web/              Astro 6 + React islands + Tailwind CSS v4 + typed RPC client
scripts/               Build, quality, scaffold, and policy scripts
policies/              Deterministic repo-policy definitions (JSON)
contracts/             Project contract definitions consumed by code generators
drizzle/               Schema migration files
config/                YAML app configuration (database URL, server port, etc.)
dockers/               Docker Compose for local observability (OTel Collector + Jaeger)
docs/                  Architecture spec, developer spec, scaffold guide, policy guide, etc.

Starter Profiles

| Profile | Included workspaces | Setup command | | --- | --- | --- | | CLI + API + Web | apps/cli, apps/server, apps/web | default checkout | | CLI + API | apps/cli, apps/server | bun run scaffold:remove -- webapp | | CLI only | apps/cli | bun run scaffold:remove -- webapp && bun run scaffold:remove -- server |

Quick Start

New project from starter

bunx degit gobing-ai/typescript-bun-starter my-project && cd my-project
bun install
bun run scaffold:init -- --name my-project --scope @acme --title "My Project"
bun run check

Use as a compiled CLI

bun run build:cli
./dist/cli/tbs scaffold init --name my-project --scope @acme --title "My Project"

Local Development

bun run dev:cli          # CLI in dev mode
bun run dev:server       # API server with --hot reload
bun run dev:web          # Astro dev server
bun run dev:all          # All three simultaneously

Verification

bun run check            # Full quality gate: format, lint, policies, typecheck, tests, coverage
bun run check:policy     # Repo policy engine only

Cloudflare Deployment

Prerequisites

• Cloudflare account
• Wrangler CLI (installed as devDependency)
• D1 database: wrangler d1 create starter-db
• KV namespace: wrangler kv:namespace create SESSION

Deploy

# Update apps/server/wrangler.toml with your D1 database_id and KV namespace id
bun run deploy:server    # Workers API
bun run deploy:web       # Pages static site

Local Cloudflare development

bun run dev:server:cf    # Miniflare (D1 + KV simulation)
bun run preview:web:cf   # Pages dev server

Cron triggers

Register jobs in apps/server/src/scheduled.ts and add matching [[triggers]] entries in apps/server/wrangler.toml. The Cloudflare runtime invokes scheduled(event) automatically. For local/VPS deployments, the scheduler uses node-cron via APP_MODE=node.

HTTP Client Boundaries

| File | Purpose | | --- | --- | | packages/core/src/api-client.ts | Generic outbound HTTP (timeouts, OTel spans, APIError for non-2xx) | | apps/web/src/lib/rpc-client.ts | Typed Hono RPC client for the project's own /api/* routes | | apps/web/src/lib/third-party-client.ts | Browser fetch wrapper for external APIs (OAuth, webhooks, vendors) | | packages/contracts/src/http-client.ts | Shared browser-safe transport helpers (header normalization, response parsing) |

Direct external API access is centralized through these wrappers, enforced by the external-api-boundaries policy.

Telemetry

OpenTelemetry helpers in @starter/core for tracing and metrics across inbound HTTP, outbound HTTP, and DB access.

# Enable
export TELEMETRY_ENABLED=true
export OTEL_SERVICE_NAME=my-service
export OTEL_ENVIRONMENT=development
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces

Runtime modes:

• TELEMETRY_ENABLED=false — disabled, server runs normally
• TELEMETRY_ENABLED=true without OTEL_EXPORTER_OTLP_ENDPOINT — spans created in-process, no remote export
• TELEMETRY_ENABLED=true with endpoint set — traces exported to collector

Local observability stack

bun run dev:observability         # Start OTel Collector + Jaeger
bun run dev:observability:logs    # Tail collector logs
bun run dev:observability:down    # Teardown

Open Jaeger at http://localhost:16686.

Custom spans

import { addSpanAttributes, addSpanEvent, traceAsync } from "@starter/core";

const result = await traceAsync("operation.name", async (span) => {
  span.setAttribute("operation.key", value);
  addSpanAttributes({ "app.operation": "operation.name" });
  addSpanEvent("operation.started", { "key": value });
  return await doWork();
});

Documentation

• Architecture Spec
• Developer Spec
• User Manual
• Scaffold Guide
• Database Access
• Policy Check
• TBS Product Spec
• Existing Project Migration Guide
• TDD for Frameworks

References

• Bun workspaces
• Install Bun in GitHub Actions

License

MIT