Como configurar um Turborepo Monorepo em 2026: guia completo com Next.js e pacotes

Turborepo é o padrão para monorepos JavaScript/TypeScript em 2026 – o cache de construção sozinho reduz o tempo de CI em 70-90% em grandes bases de código. Este guia configura um monorepo pronto para produção com dois aplicativos Next.js e pacotes compartilhados do zero.

O que estamos construindo

my-monorepo/
├── apps/
│   ├── web/          # Next.js marketing site
│   └── docs/         # Next.js documentation site
├── packages/
│   ├── ui/           # Shared React components
│   ├── utils/        # Shared utilities
│   └── tsconfig/     # Shared TypeScript configs
├── turbo.json        # Turborepo configuration
└── package.json      # Workspace root

Etapa 1: inicializar com Turborepo

# Create from official template
npx create-turbo@latest my-monorepo
cd my-monorepo

# Or manual setup
mkdir my-monorepo && cd my-monorepo
pnpm init
# pnpm is recommended for monorepos — faster, better disk usage

Etapa 2: Raiz package.json

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build":   "turbo build",
    "dev":     "turbo dev",
    "lint":    "turbo lint",
    "test":    "turbo test",
    "format":  "prettier --write "**/*.{ts,tsx,md}""
  },
  "devDependencies": {
    "turbo":     "^2.0.0",
    "prettier":  "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "pnpm@9.0.0"
}

Etapa 3: Configuração do espaço de trabalho pnpm

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

Etapa 4: turbo.json — Configuração do pipeline

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],    // build dependencies first
      "outputs": [".next/**", "dist/**", "!.next/cache/**"],
      "env": ["NODE_ENV", "NEXT_PUBLIC_*"]  // cache key includes these env vars
    },
    "dev": {
      "cache":     false,   // never cache dev servers
      "persistent": true    // keep running (don't wait for exit)
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs":   ["coverage/**"],
      "inputs":    ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs":   []
    }
  }
}

Etapa 5: Pacote de configuração TypeScript compartilhado

mkdir -p packages/tsconfig
cat > packages/tsconfig/package.json << 'EOF'
{
  "name": "@mymonorepo/tsconfig",
  "version": "0.0.0",
  "private": true,
  "files": ["*.json"]
}
EOF

// packages/tsconfig/base.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Default",
  "compilerOptions": {
    "target":           "ES2022",
    "lib":              ["ES2022", "DOM"],
    "module":           "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowJs":          true,
    "strict":           true,
    "esModuleInterop":  true,
    "skipLibCheck":     true,
    "noEmit":           true
  }
}

// packages/tsconfig/nextjs.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Next.js",
  "extends":      "./base.json",
  "compilerOptions": {
    "plugins": [{ "name": "next" }],
    "jsx":     "preserve",
    "module":  "ESNext"
  }
}

Etapa 6: Pacote de IU compartilhado

mkdir -p packages/ui/src

cat > packages/ui/package.json << 'EOF'
{
  "name": "@mymonorepo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./button":   "./src/button.tsx",
    "./card":     "./src/card.tsx"
  },
  "scripts": {
    "lint":      "eslint src/",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@mymonorepo/tsconfig": "workspace:*",
    "typescript": "^5.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0"
  }
}
EOF

// packages/ui/src/button.tsx
import { type ButtonHTMLAttributes } from "react";

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

export function Button({ variant = "primary", children, ...props }: ButtonProps) {
  return (
    <button
      className={variant === "primary" ? "btn-primary" : "btn-secondary"}
      {...props}
    >
      {children}
    </button>
  );
}

Etapa 7: Aplicativo Next.js usando pacote compartilhado

# apps/web/package.json
{
  "name": "web",
  "dependencies": {
    "@mymonorepo/ui":      "workspace:*",
    "@mymonorepo/utils":   "workspace:*",
    "next":                "^15.0.0",
    "react":               "^19.0.0"
  },
  "devDependencies": {
    "@mymonorepo/tsconfig": "workspace:*"
  }
}

// apps/web/tsconfig.json
{
  "extends": "@mymonorepo/tsconfig/nextjs.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

// apps/web/app/page.tsx
import { Button } from "@mymonorepo/ui/button";  // shared component

export default function HomePage() {
  return (
    <main>
      <h1>Welcome</h1>
      <Button variant="primary">Get Started</Button>
    </main>
  );
}

Etapa 8: Executando o Monorepo

# Install all dependencies
pnpm install

# Run all dev servers in parallel
pnpm dev

# Build all apps and packages (with caching)
pnpm build

# Build only one app
pnpm turbo build --filter=web

# Build only changed packages (incremental)
pnpm turbo build --filter="[HEAD^1]"

Etapa 9: Cache remoto para CI

# Turbo remote cache with Vercel (free tier available)
npx turbo login
npx turbo link

# Now CI can use remote cache — artifacts shared across team
# .github/workflows/ci.yml
- name: Build
  run: pnpm turbo build
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM:  ${{ vars.TURBO_TEAM }}

Taxas de acerto de cache na prática: Em uma equipe de 5 desenvolvedores, taxas de acerto de cache de 70 a 80% são comuns na CI. Uma compilação que leva 8 minutos na primeira execução geralmente leva menos de 1 minuto com ocorrências de cache — o ROI é significativo para qualquer equipe que executa CI várias vezes por dia.

Perguntas Frequentes

P: pnpm vs npm vs yarn para monorepos?
R: pnpm é a escolha certa para monorepos em 2026 – node_modules com link simbólico usam 60-80% menos espaço em disco em comparação com npm, o protocolo de espaço de trabalho (workspace:*) é mais confiável e a instalação é significativamente mais rápida. A maioria dos novos projetos Turborepo usa pnpm.

P: Quando devo usar um monorepo?
R: Quando você tem mais de 2 projetos relacionados compartilhando código (tipos, componentes, utilitários). Projeto único: não se preocupe. 2-3 aplicativos intimamente relacionados: o monorepo compensa rapidamente. O ponto de equilíbrio é aproximadamente “você está cansado de copiar funções utilitárias entre repositórios”.

P: Como adiciono um novo pacote?
A: mkdir packages/my-package && cd packages/my-package && pnpm init, adicione-o ao espaço de trabalho e, em seguida,pnpm install. O pacote está imediatamente disponível viaworkspace:* em outros pacotes.

P: O Turborepo é melhor que o Nx?
R: O Turborepo é mais simples de instalar e configurar. Nx tem mais geradores integrados e um ecossistema de plugins mais rico. Turborepo para equipes menores que desejam simplicidade; Nx para grandes organizações com gráficos de construção complexos. Ambos são comprovados em produção.

P: Como implantar aplicativos individuais de um monorepo?
R: Vercel e Netlify têm suporte nativo a monorepo – configure “Root Directory” para o subdiretório do aplicativo. Como alternativa, use o Docker comCOPY . . na raiz do monorepo eturbo build --filter=app-name.

Conclusão

Turborepo transforma o desenvolvimento JavaScript de vários aplicativos, eliminando compilações redundantes e compartilhando código de forma limpa. A configuração – espaços de trabalho pnpm, pacote tsconfig compartilhado, pacote de UI compartilhado, pipeline turbo.json, cache remoto – leva cerca de 2 horas para ser configurada, mas compensa em cada construção subsequente. Comece com o modelo create-turbo para obter o caminho mais rápido ou siga este guia para obter uma configuração totalmente personalizada que corresponda à estrutura real do seu projeto.