Monorepos and Turborepo

Why This Matters#

As an engineering organization expands, product development rarely remains confined to a single standalone web application. A family of interconnected platforms naturally emerges: a public customer portal (B2C), an authenticated administrative console (B2B Admin Dashboard), customer-facing documentation, landing pages, and marketing microsites. Housing these codebases in disconnected, isolated polyrepo repositories generates massive code duplication: design systems (UI Kits), domain TypeScript contracts, linter configurations, and business utilities are duplicated across repositories, and changing a single core button requires dozens of coordinated pull requests.

A Monorepo resolves this operational overhead by centralizing the codebase within a unified repository. Internal packages are linked directly via local workspace protocols without requiring intermediate package releases to public or private npm registries.

However, monorepos lacking intelligent build systems suffer from severe build performance degradation: editing a single documentation markdown file must never trigger a complete rebuild of the enterprise web application and admin dashboard. To orchestrate tasks, resolve dependency graphs, and compute cache invalidations, modern architectures adopt Turborepo. Turborepo prevents redundant computation through cryptographic hashing and Remote Caching.

Mental Model#

In a monorepo architecture powered by pnpm Workspaces, a clear separation of concerns is maintained:

• apps/* — Terminal consumers (Next.js applications). They import shared packages, but no external package or application ever imports code from apps/.
• packages/* — Shared reusable libraries (UI components, domain schemas, shared configurations, database ORM clients).

MONOREPO ROOT
                 ┌─────────────────────────────────────────────────┐
                 │  pnpm-workspace.yaml | turbo.json | package.json │
                 └────────────────────────┬────────────────────────┘
                                          │
                  ┌───────────────────────┴───────────────────────┐
                  ▼                                               ▼
          [apps/ (Consumers)]                           [packages/ (Libraries)]
   ┌───────────────────────────────┐               ┌─────────────────────────────────┐
   │ apps/web (Next.js 15 App)     │               │ packages/ui (Design System)     │
   │ apps/admin (Next.js Admin)    │ ────────────► │ packages/types (Interfaces)     │
   │ apps/docs (Documentation)     │   workspace:* │ packages/tsconfig (TS Configs)  │
   └───────────────────────────────┘               │ packages/database (Prisma/ORM)  │
                  │                                └─────────────────────────────────┘
                  │ turbo prune                                    ▲
                  ▼                                                │
   ┌───────────────────────────────┐                               │
   │ Docker OCI Image (@acme/web)  │ ──────────────────────────────┘
   │ (Contains strictly web + ui)  │
   └───────────────────────────────┘

Syntax and API#

1. Workspace Root Manifest: pnpm-workspace.yaml#

At the monorepo root, pnpm-workspace.yaml defines the discovery boundaries for workspace packages:

packages:
  - "apps/*"
  - "packages/*"

2. Turborepo v2 Configuration: turbo.json#

Under Turborepo 2.x standards, the root configuration section is named tasks (replacing the deprecated pipeline), and environment variables must be declared explicitly to prevent Cache Poisoning:

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "globalEnv": ["NODE_ENV", "VERCEL_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "env": ["NEXT_PUBLIC_API_URL", "DATABASE_URL"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

3. Creating an Internal JIT Package#

In packages/ui, React is placed strictly in peerDependencies to prevent multi-instance conflicts:

{
  "name": "@acme/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": "./src/index.ts"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@types/react": "^19.0.0",
    "react": "^19.0.0",
    "typescript": "^5.7.0"
  }
}

Connecting the package inside an application (apps/web/package.json) uses the workspace:* protocol:

{
  "name": "@acme/web",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@acme/ui": "workspace:*",
    "next": "^15.2.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

Practical Patterns#

1. Transpilation in Next.js: transpilePackages#

Because @acme/ui ships uncompiled TypeScript, the Next.js compiler (Turbopack) must transpile it on the fly:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  transpilePackages: ['@acme/ui'],
};

export default nextConfig;

2. TypeScript Configuration Inheritance#

Rather than copying compiler options across projects, create a shared base package packages/typescript-config/nextjs.json:

{
  "extends": "@acme/typescript-config/nextjs.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"]
}

3. Tailwind CSS v4 Integration Across Monorepo Packages#

In Tailwind CSS v4, scanning utility classes in shared design system packages is achieved using the @source directive in the application's root stylesheet:

@import "tailwindcss";

/* Direct Tailwind v4 compiler to scan shared workspace package components */
@source "../../../../packages/ui/src/**/*.tsx";

Common Pitfalls#

{
  "pnpm": {
    "overrides": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    }
  }
}

Interview Questions#