Setting Up Monorepo (Turborepo) for Web Project
Turborepo — build system for monorepo from Vercel. Not a package manager, not a linter — precisely a tool for smart task execution with result caching. Main idea: if task inputs haven't changed, output is taken from cache. In practice, this means turbo build in 3 seconds instead of 4 minutes on repeat run.
When Turborepo, Not Just npm Workspaces
npm/yarn/pnpm workspaces already give monorepo structure with shared dependencies. Turborepo adds on top:
- Parallel execution considering inter-package dependencies
- Incremental cache (local + remote)
- Task graph with explicit dependencies
- Filtering: run only changed packages
For small projects (2–3 packages) and small team — workspaces without Turbo suffice. At 5+ packages and CI/CD — Turbo starts saving real time.
Project Structure
my-project/
├── apps/
│ ├── web/ # Next.js frontend
│ ├── admin/ # Vite + React admin panel
│ └── api/ # Node.js/Express backend
├── packages/
│ ├── ui/ # shared React components
│ ├── config/
│ │ ├── eslint/ # ESLint config
│ │ ├── typescript/ # base tsconfig
│ │ └── tailwind/ # tailwind preset
│ ├── utils/ # common utilities (formatDate, etc.)
│ └── types/ # shared TypeScript types
├── package.json # workspaces declaration
├── turbo.json # Turborepo config
└── pnpm-workspace.yaml # if using pnpm
Initialization
# Create new monorepo
npx create-turbo@latest my-project
cd my-project
# Or add Turbo to existing project
pnpm add turbo --save-dev --workspace-root
turbo.json Configuration
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": [".env"],
"pipeline": {
"build": {
"dependsOn": ["^build"],
"inputs": ["src/**", "package.json", "tsconfig.json"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"],
"env": ["NODE_ENV", "API_URL"]
},
"dev": {
"cache": false,
"persistent": true
},
"lint": {
"inputs": ["src/**", "*.ts", "*.tsx", ".eslintrc*"],
"outputs": []
},
"typecheck": {
"dependsOn": ["^build"],
"inputs": ["src/**", "tsconfig.json"],
"outputs": []
},
"test": {
"dependsOn": ["^build"],
"inputs": ["src/**", "test/**", "vitest.config.*"],
"outputs": ["coverage/**"],
"env": ["TEST_DATABASE_URL"]
},
"test:e2e": {
"dependsOn": ["build"],
"inputs": ["e2e/**", "playwright.config.*"],
"outputs": ["test-results/**"],
"cache": false
},
"db:generate": {
"cache": false,
"inputs": ["prisma/schema.prisma"]
}
}
}
^build means "first build all dependencies of this package". Turbo automatically determines order: packages/ui will build before apps/web because web depends on ui.
Configuring Packages
// packages/ui/package.json
{
"name": "@acme/ui",
"version": "0.0.0",
"private": true,
"exports": {
".": {
"import": "./dist/index.js",
"types": "./dist/index.d.ts"
},
"./styles": "./dist/styles.css"
},
"scripts": {
"build": "tsup src/index.ts --format esm --dts",
"dev": "tsup src/index.ts --format esm --dts --watch",
"lint": "eslint src/",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"@acme/eslint-config": "*",
"@acme/typescript-config": "*",
"tsup": "^8.0.0"
},
"peerDependencies": {
"react": "^18.0.0"
}
}
// apps/web/package.json
{
"name": "@acme/web",
"private": true,
"dependencies": {
"@acme/ui": "*",
"@acme/utils": "*"
}
}
"*" — workspace protocol: pnpm/yarn resolves to local package. In npm must specify "workspace:*" explicitly.
Shared TypeScript Config
// packages/config/typescript/base.json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "Bundler",
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"lib": ["ES2020"],
"skipLibCheck": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true
}
}
// packages/config/typescript/react.json
{
"extends": "./base.json",
"compilerOptions": {
"jsx": "react-jsx",
"lib": ["ES2020", "DOM", "DOM.Iterable"]
}
}
// apps/web/tsconfig.json
{
"extends": "@acme/typescript-config/react.json",
"compilerOptions": {
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
},
"include": ["src", "next-env.d.ts"]
}
Remote Cache
Local cache works on one machine only. For team and CI need remote cache. Vercel Remote Cache — free for open source, paid for private:
# Authorization (once)
npx turbo login
npx turbo link
# Or self-hosted via ducktape/turborepo-remote-cache
Self-hosted option via turborepo-remote-cache (open server):
# docker-compose.yml for remote cache server
services:
turbo-cache:
image: ducktors/turborepo-remote-cache:latest
ports:
- "3000:3000"
environment:
TURBO_TOKEN: "your-secret-token"
STORAGE_PROVIDER: "s3"
S3_BUCKET: "turbo-cache-bucket"
AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
// turbo.json — remote cache endpoint
{
"remoteCache": {
"signature": true
}
}
# Run with remote cache
TURBO_TOKEN=your-secret-token TURBO_API=https://cache.internal.example.com \
turbo build
CI/CD with Turborepo
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
ci:
runs-on: ubuntu-latest
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2 # needed for --filter=...[HEAD^1]
- uses: pnpm/action-setup@v3
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
# Run only tasks for changed packages
- run: pnpm turbo lint typecheck test --filter=...[HEAD^1]
# Build always — deploy needs current cache
- run: pnpm turbo build
--filter=...[HEAD^1] — "everything changed since last commit, plus all packages depending on this". If you change packages/ui — both apps/web and apps/admin rebuild.
Common Issues
Runtime config dependency — if package reads .env at build time, Turbo will cache with specific value. Explicitly specify env in pipeline:
"build": {
"env": ["NEXT_PUBLIC_API_URL", "DATABASE_URL"]
}
Circular dependencies — Turbo fails with error. Refactor: extract common dependency into third package.
Dev mode and cache — dev should have "cache": false and "persistent": true. Otherwise Turbo won't run watchers in parallel.
Timeline
Setting up Turborepo from scratch for 5–8 package project — two to three days: creating structure, configuring pipeline, shared tsconfig/eslint, setting up remote cache, adapting CI/CD. Migrating existing project to monorepo adds a week for restructuring imports and resolving dependencies.