Guia Turborepo Monorepo: Gerenciando projetos de vários aplicativos

Monorepos contendo vários aplicativos e pacotes compartilhados são agora a arquitetura padrão para empresas que criam produtos de software interconectados. O Turborepo, adquirido pela Vercel, fornece a camada de orquestração de construção que torna os monorepos práticos – lidando com dependências de tarefas, armazenamento em cache e execução paralela em dezenas de pacotes.

Principais conclusões

• O cache remoto Turborepo pode reduzir o tempo de construção de CI em 80-90% em alterações incrementais
• Pipelines de tarefas garantem que os pacotes sejam construídos automaticamente na ordem de dependência correta
• Pacotes compartilhados (tipos, validadores, utilitários) eliminam a duplicação de código entre aplicativos
• Os espaços de trabalho pnpm fornecem gerenciamento de dependência com eficiência de disco para monorepos

---

Arquitetura Monorepo

Estrutura de diretório

Um monorepo Turborepo típico separa aplicativos de pacotes compartilhados:

my-monorepo/
  apps/
    api/           # NestJS backend
    web/           # Next.js frontend
    docs/          # Documentation site
    mobile/        # React Native app
  packages/
    db/            # Drizzle ORM schemas and migrations
    types/         # Shared TypeScript types
    validators/    # Zod validation schemas
    utils/         # Shared utility functions
    ui/            # Shared UI components
    config/        # Shared configuration (ESLint, TypeScript)
  turbo.json       # Turborepo configuration
  pnpm-workspace.yaml
  package.json     # Root package.json

Configuração do espaço de trabalho

Defina espaços de trabalho em pnpm-workspace.yaml:

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

Cada espaço de trabalho possui seu próprio package.json com dependências e scripts. Pacotes compartilhados são referenciados usando o protocolo de espaço de trabalho:

{
  "dependencies": {
    "@myorg/types": "workspace:*",
    "@myorg/validators": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

---

Configuração do Turborepo

Pipeline de tarefas

turbo.json define como as tarefas se relacionam entre si:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

Conceitos principais:

• dependsOn: ["^build"]: O acento circunflexo (^) significa "construir todas as dependências primeiro." Ao construir o aplicativo da web, o Turborepo cria pacotes/tipos, pacotes/validadores e pacotes/utilitários primeiro.
• saídas: Arquivos que o Turborepo armazena em cache. Nas execuções subsequentes, se as entradas não tiverem sido alteradas, o Turborepo reproduzirá a saída armazenada em cache em vez de reconstruí-la.
• persistent: true: Para servidores de desenvolvimento que continuam em execução.
• cache: false: Desativa o cache para tarefas que devem sempre ser executadas (como servidores de desenvolvimento).

---

Pacotes Compartilhados

Pacote de Tipos

Centralize os tipos TypeScript usados em aplicativos:

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user" | "support";
  createdAt: Date;
}

export type CreateUserDTO = Omit<User, "id" | "createdAt">;
export type UpdateUserDTO = Partial<CreateUserDTO>;

Pacote de validadores

Esquemas Zod compartilhados entre frontend e backend:

// packages/validators/src/user.ts
import { z } from "zod";

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(255),
  role: z.enum(["admin", "user", "support"]),
});

Configuração de compilação

Os pacotes compartilhados devem ser pré-construídos antes que os aplicativos possam consumi-los. Configure cada pacote com um script de construção que compila TypeScript para JavaScript:

{
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "dev": "tsc --watch"
  }
}

---

Estratégia de cache

Cache Local

O Turborepo armazena em cache as saídas de tarefas em node_modules/.cache/turbo por padrão. Quando você executa o turbo build e nada muda, o Turborepo reproduz a saída armazenada em cache em milissegundos.

Cache Remoto

Para CI/CD, habilite o cache remoto para compartilhar artefatos de construção entre membros da equipe e execuções de CI:

npx turbo login
npx turbo link

Cache remoto significa que uma compilação concluída em uma máquina de desenvolvedor ou execução de CI está disponível para todos. O impacto é dramático: as compilações incrementais de CI caem de 10 minutos para menos de 1 minuto.

---

Fluxo de trabalho de desenvolvimento

Executando todos os aplicativos

pnpm dev       # Starts all apps and watches all packages

O Turborepo cria pacotes compartilhados primeiro (porque o dev depende do ^build) e, em seguida, inicia os servidores de desenvolvimento de aplicativos em paralelo. Alterações em pacotes compartilhados acionam recriações que se propagam para aplicativos de consumo.

Executando aplicativos específicos

pnpm dev --filter=web     # Only the web app and its dependencies
pnpm dev --filter=api     # Only the API and its dependencies

A filtragem é essencial para grandes monorepos onde é desnecessário iniciar tudo.

---

Otimização de CI/CD

Detecção de pacotes afetados

O Turborepo determina quais pacotes foram alterados desde o último commit e executa tarefas apenas para os pacotes afetados:

turbo build --filter=...[HEAD^1]

Isso executa build apenas para pacotes que foram alterados no commit mais recente e seus dependentes.

Execução Paralela

Turborepo executa tarefas independentes em paralelo. Se pacotes/tipos e pacotes/utils não tiverem relacionamento de dependência, eles serão compilados simultaneamente. O nível de simultaneidade se adapta aos núcleos de CPU disponíveis.

---

Perguntas frequentes

P: Quantos pacotes um Turborepo monorepo pode manipular?

Turborepo lida com monorepos com centenas de pacotes. O desempenho é bem dimensionado porque o gráfico da tarefa é analisado na inicialização e o armazenamento em cache significa que a maioria dos pacotes ignora compilações em alterações incrementais.

Q: Should we use pnpm or npm for workspaces?

pnpm é fortemente recomendado para monorepos. Seu armazenamento endereçável por conteúdo desduplica dependências entre pacotes, economizando espaço em disco e tempo de instalação significativos. Os espaços de trabalho pnpm também são mais rigorosos quanto à resolução de dependências, capturando declarações de dependência ausentes.

P: Como lidamos com diferentes versões do Node.js em aplicativos?

Use o campo de mecanismos em cada package.json para especificar os requisitos de versão do Node.js. Para diferenças de tempo de execução, configure o CI para usar a versão apropriada por aplicativo.

P: Podemos adotar o Turborepo de forma incremental?

Sim. Adicione turbo.json a um projeto de espaço de trabalho pnpm existente e configure pipelines de tarefas. Os scripts existentes continuam funcionando. Você obtém armazenamento em cache e orquestração de tarefas imediatamente, sem reestruturação.

---

O que vem a seguir

Turborepo transforma o desenvolvimento de monorepo de uma carga de manutenção em um multiplicador de produtividade. Comece com uma estrutura simples e cresça conforme o seu projeto exigir.

Entre em contato com a ECOSIRE para consultoria de arquitetura monorepo ou explore nossos serviços de integração Odoo para arquiteturas ERP de vários aplicativos.

---

Publicado pela ECOSIRE – ajudando empresas a escalar com soluções de software empresarial.