Gerenciamento de Monorepo

Crie monorepos eficientes e escaláveis que permitam o compartilhamento de código, ferramentas consistentes e alterações atômicas em vários pacotes e aplicativos.

Quando Usar Esta Habilidade

• Configurando novos projetos de monorepo
• Migrando de multi-repo para monorepo
• Otimizando o desempenho de build e testes
• Gerenciando dependências compartilhadas
• Implementando estratégias de compartilhamento de código
• Configurando CI/CD para monorepos
• Versionando e publicando pacotes
• Depurando problemas específicos de monorepo

Conceitos Principais

1. Por que Monorepos?

Vantagens:

• Código e dependências compartilhados
• Commits atômicos entre projetos
• Ferramentas e padrões consistentes
• Refatoração mais fácil
• Gerenciamento de dependências simplificado
• Melhor visibilidade do código

Desafios:

• Desempenho de build em escala
• Complexidade de CI/CD
• Controle de acesso
• Grande repositório Git

2. Ferramentas de Monorepo

Gerenciadores de Pacotes:

• pnpm workspaces (recomendado)
• npm workspaces
• Yarn workspaces

Sistemas de Build:

• Turborepo (recomendado para a maioria)
• Nx (rico em recursos, complexo)
• Lerna (antigo, modo de manutenção)

Configuração do Turborepo

Configuração Inicial

# Create new monorepo
npx create-turbo@latest my-monorepo
cd my-monorepo

# Structure:
# apps/
#   web/          - Next.js app
#   docs/         - Documentation site
# packages/
#   ui/           - Shared UI components
#   config/       - Shared configurations
#   tsconfig/     - Shared TypeScript configs
# turbo.json      - Turborepo configuration
# package.json    - Root package.json

Configuração

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "pnpm@8.0.0"
}

O pnpm lê os pacotes do workspace apenas de pnpm-workspace.yaml, então declare-os lá (veja references/details.md). O Turborepo 2 renomeou pipeline para tasks e rejeita um turbo.json que ainda usa pipeline; execute npx @turbo/codemod migrate para atualizar uma configuração 1.x.

Estrutura de Pacotes

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "tsup": "^7.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

Padrões Detalhados e Exemplos Trabalhados

A documentação detalhada de padrões reside em references/details.md. Leia esse arquivo quando o nível de navegação acima for insuficiente.

Melhores Práticas

1. Versionamento Consistente: Trave as versões das dependências em todo o workspace
2. Configurações Compartilhadas: Centralize as configurações do ESLint, TypeScript, Prettier
3. Grafo de Dependências: Mantenha-o acíclico, evite dependências circulares
4. Cache Eficaz: Configure as entradas/saídas corretamente
5. Segurança de Tipos: Compartilhe tipos entre frontend/backend
6. Estratégia de Testes: Testes unitários em pacotes, E2E em aplicativos
7. Documentação: README em cada pacote
8. Estratégia de Lançamento: Use changesets para versionamento

Armadilhas Comuns

• Dependências Circulares: A depende de B, B depende de A
• Dependências Fantasmas: Usando dependências que não estão no package.json
• Entradas de Cache Incorretas: Arquivos ausentes nas entradas do Turborepo
• Compartilhamento Excessivo: Compartilhando código que deveria ser separado

…