Next.js Monorepo with Turborepo: Enterprise Architecture

Managing multiple Next.js applications — marketing site, dashboard, admin panel, API service — under a single repository requires deliberate architecture. Without structure, you get duplicated configurations, inconsistent dependency versions, and CI pipelines that rebuild everything for every change.

Turborepo solves these problems with parallel task execution, remote caching, and a dependency graph that knows exactly which packages need rebuilding. This guide covers the complete setup: project structure, shared packages, TypeScript configuration, CI/CD optimization, and deployment.

Why Monorepo? The Case for a Single Repository

In enterprise environments, managing multiple Next.js applications independently leads to duplicated code, inconsistent dependencies, and fragile cross-project coordination. A monorepo consolidates all projects into one repository, enabling shared linting, testing, and build configurations. Turborepo adds intelligent caching and parallel execution, reducing CI times from hours to minutes. The key trade-off is increased repository size and the need for disciplined code ownership boundaries. For teams with 3+ Next.js apps, the benefits far outweigh the costs.

npx create-turbo@latest my-enterprise --example with-nextjs
cd my-enterprise
npm install

Turborepo Architecture: Pipelines and Caching

Turborepo's core is the pipeline configuration in turbo.json. It defines task dependencies and caching rules. For example, build depends on ^build (upstream packages built first), and test depends on build. Turborepo caches outputs based on file contents, environment variables, and dependency graphs. Remote caching (via Vercel or S3) shares cache across CI runners, making cold builds as fast as incremental ones. Misconfigured pipelines (e.g., missing dependsOn) cause stale builds or unnecessary rebuilds.

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "public/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.test.ts", "src/**/*.spec.ts"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Structuring the Workspace: Apps and Packages

A typical enterprise monorepo has apps/ for Next.js applications and packages/ for shared libraries. Each app is a standalone Next.js project with its own next.config.js. Shared packages include UI components (@mycompany/ui), utilities (@mycompany/utils), and configuration (@mycompany/eslint-config). Use TypeScript project references for type checking across packages. Avoid circular dependencies by enforcing a strict dependency graph: packages can depend on other packages but not on apps.

{
  "name": "@mycompany/ui",
  "version": "0.1.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "typescript": "^5.0.0"
  }
}

Shared TypeScript Configuration

Consistency across the monorepo starts with a shared tsconfig.json base. Extend it in each app/package using extends. Use strict mode, enable composite for project references, and set declarationMap for better editor support. For Next.js apps, include jsx: "preserve" and moduleResolution: "bundler". For packages, use module: "commonjs" or "esnext" depending on your target. A common pitfall is forgetting to set rootDir and outDir correctly, causing type errors in consuming apps.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true
  }
}

Shared ESLint and Prettier Configuration

Enforce code style across the monorepo with a shared ESLint config that extends next/core-web-vitals and turbo. Use Prettier for formatting, integrated via eslint-config-prettier. For packages that don't use React, create a separate base config. Run linting in CI with turbo run lint to check all workspaces. A common mistake is having conflicting rules between the root config and workspace configs; use root: true in the root .eslintrc.js to prevent inheritance issues.

module.exports = {
  extends: [
    'next/core-web-vitals',
    'turbo',
    'prettier',
  ],
  rules: {
    'react/no-unescaped-entities': 'off',
    '@next/next/no-img-element': 'off',
  },
};

Building Shared UI Components with Next.js

Shared UI components (buttons, modals, forms) should be built as a separate package using React and TypeScript. Export components as named exports from an index file. Use next/dynamic for code splitting in apps, but avoid it in the shared package to keep bundle optimization at the app level. For styling, use CSS Modules or Tailwind CSS with a shared preset. Ensure components are server-component compatible by marking them with 'use client' only when necessary.

import React from 'react';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
}

export const Button: React.FC<ButtonProps> = ({ variant = 'primary', children, ...props }) => {
  const baseClasses = 'px-4 py-2 rounded font-medium';
  const variantClasses = variant === 'primary' ? 'bg-blue-600 text-white' : 'bg-gray-200 text-gray-800';
  return (
    <button className={`${baseClasses} ${variantClasses}`} {...props}>
      {children}
    </button>
  );
};

Managing Environment Variables Across Apps

Each Next.js app has its own .env.local for secrets and .env for defaults. For shared variables (e.g., API base URL), create a .env file at the root and reference it in each app's next.config.js using env option. Turborepo can pass environment variables via turbo.json's globalEnv to invalidate cache when they change. Never commit .env.local files; use .env.example as a template. A common failure is missing a variable in production, causing silent failures.

const path = require('path');
require('dotenv').config({ path: path.resolve(__dirname, '../../.env') });

module.exports = {
  env: {
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
};

Testing Strategy: Unit, Integration, and E2E

Use Jest for unit tests in packages and apps, with @testing-library/react for UI components. For integration tests across apps, use Playwright or Cypress. Run tests with turbo run test to leverage caching. Keep test files co-located with source files (e.g., Button.test.tsx). For E2E tests, create a separate package @mycompany/e2e that depends on all apps. A common pitfall is slow test suites due to unnecessary rebuilds; use Turborepo's inputs to only run tests on changed files.

import { render, screen } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('renders with primary variant', () => {
    render(<Button variant="primary">Click me</Button>);
    const button = screen.getByRole('button', { name: /click me/i });
    expect(button).toHaveClass('bg-blue-600');
  });
});

CI/CD Pipeline with Turborepo and GitHub Actions

Optimize CI by using Turborepo's remote caching. In GitHub Actions, set up a cache key based on turbo.json and lockfile. Use turbo run lint test build to run all checks. For deployment, deploy each app independently (e.g., to Vercel or AWS). Use turbo prune --scope=@mycompany/admin to create a minimal deployable artifact. A common mistake is not caching node_modules separately, causing long install times.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
      - run: npm ci
      - run: npx turbo run lint test build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Handling Dependencies and Versioning

Use npm workspaces (or pnpm) for dependency management. Keep shared dependencies (React, Next.js) at the root package.json to ensure single version. For package-specific dependencies, declare them in the package's package.json. Use npm update carefully; prefer npm install package@version to avoid accidental upgrades. A common issue is hoisting conflicts where two packages require different versions of the same dependency; use overrides in root package.json to force a single version.

{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "overrides": {
    "react": "^18.2.0",
    "next": "^14.0.0"
  }
}

Deploying Next.js Apps from Monorepo

Deploy each Next.js app independently. For Vercel, connect the monorepo and configure each app's root directory (e.g., apps/admin). Use turbo prune to generate a minimal deployment folder. For Docker, create a multi-stage build that copies only the pruned workspace. Ensure environment variables are set per app in the deployment platform. A common failure is deploying the entire monorepo, causing bloated images and slow cold starts.

FROM node:20-alpine AS builder
WORKDIR /app
COPY . .
RUN npx turbo prune --scope=@mycompany/admin --docker

FROM node:20-alpine AS installer
WORKDIR /app
COPY --from=builder /app/out/json .
COPY --from=builder /app/out/package-lock.json .
RUN npm ci
COPY --from=builder /app/out/full .
RUN npx turbo run build --filter=@mycompany/admin

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=installer /app/apps/admin/.next ./.next
COPY --from=installer /app/apps/admin/public ./public
COPY --from=installer /app/apps/admin/package.json .
EXPOSE 3000
CMD ["npm", "start"]

Monitoring and Debugging in Production

Use structured logging with pino or winston in API routes and server components. Aggregate logs using a service like Datadog or Grafana. For error tracking, integrate Sentry with each Next.js app. Turborepo doesn't affect runtime monitoring, but ensure each app has its own sentry.client.config.js and sentry.server.config.js. A common mistake is not distinguishing between apps in logs, making debugging cross-app issues difficult.

import { NextRequest, NextResponse } from 'next/server';
import pino from 'pino';

const logger = pino({ level: 'info', name: 'admin-api' });

export async function POST(request: NextRequest) {
  const body = await request.json();
  logger.info({ body }, 'Received log event');
  return NextResponse.json({ status: 'ok' });
}