Monorepo

Leave Localhost is organized as a Turborepo monorepo managed with Bun. This structure lets all apps and packages share types, utilities, and build configuration while remaining independently deployable.

Leave Localhost is organized as a Turborepo monorepo managed with Bun. This structure lets all apps and packages share types, utilities, and build configuration while remaining independently deployable.

Workspace Layout

leave-localhost-starter/
├── apps/
│   ├── app/              # Authenticated product app (Next.js App Router)
│   ├── marketing/        # Public marketing site (Next.js App Router)
│   └── docs/             # Documentation site (Fumadocs)
├── packages/
│   ├── backend/          # Convex backend (schema, functions, auth, billing)
│   ├── ui/               # Shared UI components, tokens, and utilities
│   ├── email/            # React Email preview server for the backend templates
│   └── analytics/        # Provider-neutral analytics (PostHog + no-op)
├── tooling/
│   └── env-doctor/       # Local environment validation CLI
├── docs/                 # Documentation (this directory)
├── turbo.json            # Turborepo task pipeline configuration
├── package.json          # Root workspace definition
└── bun.lock              # Bun lockfile

Ownership Rules

Location	Contains
`packages/ui`	Shared UI components, design tokens, and utilities
`packages/backend/convex`	All Convex schema, queries, mutations, actions, auth, billing
`apps/app`	Product-only UI, authenticated workflows, i18n
`apps/marketing`	Marketing pages and public-facing components
`packages/email`	React Email preview server (renders the backend templates)
`packages/analytics`	Provider-neutral analytics boundary (PostHog + no-op)
`tooling/env-doctor`	Setup validation scripts and tests

Package Manager

The project uses Bun exclusively:

# Install dependencies
bun install

# Run a root script
bun run <script>

# Run a workspace-specific script
bun --cwd <workspace> <script>

# Run a CLI tool
bunx <cli>

Do not use npm, pnpm, yarn, or npx unless a specific tool requires it.

Turborepo Tasks

The turbo.json at the root defines the task pipeline:

Task	Description	Cacheable
`build`	Production builds for all apps	Yes
`dev`	Development servers (persistent)	No
`typecheck`	TypeScript type checking	Yes
`lint`	Biome linting	Yes
`test`	Run test suites	No
`clean`	Remove build artifacts and caches	No

Running Tasks

# Build everything
bun run build

# Typecheck all packages
bun run typecheck

# Lint all packages
bun run lint

# Run tests
bun run test

# Development mode
bun run dev

Filtering

Run tasks for a specific workspace using Turborepo's --filter:

# Build only the product app
bunx turbo build --filter=apps/app

# Typecheck only the backend
bunx turbo typecheck --filter=packages/backend

Inter-Package Dependencies

Packages reference each other by name in their package.json:

{
  "dependencies": {
    "@leavelocalhost/ui": "workspace:*",
    "@leavelocalhost/analytics": "workspace:*"
  }
}

Turborepo ensures packages build in dependency order via dependsOn: ["^build"] and dependsOn: ["^topo"] entries.

Verification Commands

Run these before pushing changes:

After	Run
TypeScript changes	`bun run typecheck`
UI/component changes	`bun run lint`
Env validation changes	`bun test tooling/env-doctor`
Before broad PRs	`bun run lint && bun run typecheck && bun run test`
Before production	`bun run build`

Generated and Local Files

Do not manually edit or commit:

packages/backend/convex/_generated/** — auto-generated by Convex
.env, .env.local — local environment variables
.next, .turbo, .react-email, node_modules — build output

Next Reads

Convex Backend — how the backend package is organized.
Architecture Overview — high-level architecture.

On this page