Monorepositório com TypeScript: organização de código para iniciantes

Monorepositório com TypeScript: organização de código para iniciantes

O desenvolvimento de aplicações modernas em TypeScript frequentemente exige o gerenciamento de vários pacotes inter-relacionados (por exemplo, uma biblioteca de componentes, um serviço backend e utilitários). Em vez de armazenar cada pacote em um repositório separado (multirrepositório), muitas equipes optam pelo monorepositório — um repositório único contendo todos os projetos. Neste artigo, vamos explicar como organizar um monorepositório com TypeScript, mesmo que você seja iniciante.

O que é um monorepositório e por que ele é necessário?

Monorepositório (monorepo) é uma abordagem na qual o código de vários projetos (pacotes, módulos) é armazenado em um único repositório. Isso não significa que todos os projetos são misturados em uma única bagunça: eles permanecem logicamente separados, mas estão sob o mesmo teto.

Vantagens para projetos em TypeScript:

• Versão única de dependências. Você evita situações em que diferentes pacotes usam versões diferentes do TypeScript ou da mesma biblioteca.
• Refatoração simples. Alterar uma interface ou tipo comum em um lugar atualiza imediatamente todos os pacotes dependentes.
• Publicação simplificada. Ferramentas para monorepositório (como Lerna ou Nx) ajudam a publicar automaticamente apenas os pacotes alterados.
• Configurações compartilhadas. Você pode ter um único tsconfig.json para todos os pacotes, sobrescrevendo-o quando necessário.

Ferramentas para criar um monorepositório

Para trabalhar com monorepositório em TypeScript, existem várias ferramentas populares:

• npm Workspaces — funcionalidade nativa do npm a partir da versão 7. Simples e eficiente.
• Yarn Workspaces — função similar no gerenciador de pacotes Yarn.
• Lerna — ferramenta clássica, frequentemente usada em conjunto com npm ou Yarn Workspaces.
• Nx — sistema poderoso para monorepositórios com recursos avançados de cache e geração de código.
• Turborepo — ferramenta moderna da Vercel, focada em velocidade e simplicidade.

Neste guia, usaremos o npm Workspaces, pois é a maneira mais simples, sem necessidade de instalar ferramentas globais adicionais.

Configuração passo a passo de um monorepositório com TypeScript

1. Criando a estrutura raiz

Comece criando a pasta raiz do seu monorepositório e inicializando o package.json:

mkdir my-monorepocd my-monoreponpm init -y

Agora edite o package.json raiz, adicionando o campo workspaces. Isso informará ao npm onde encontrar seus pacotes:

{  "name": "my-monorepo",  "private": true,  "workspaces": [    "packages/*"  ]}

A flag "private": true evita a publicação acidental do pacote raiz no npm.

2. Criando os pacotes

Crie a estrutura de pastas para seus pacotes. Uma estrutura típica é assim:

my-monorepo/├── packages/│   ├── utils/          # Utilitários comuns│   ├── ui/             # Biblioteca de componentes│   └── backend/        # Aplicação servidora├── package.json└── tsconfig.json

Crie a pasta packages e, dentro dela, pastas para cada pacote. Cada pacote deve ter seu próprio package.json. Por exemplo, para o pacote utils:

mkdir -p packages/utilscd packages/utilsnpm init -y

Edite o packages/utils/package.json, adicionando o nome e, possivelmente, a versão:

{  "name": "@my-project/utils",  "version": "1.0.0",  "main": "dist/index.js",  "types": "dist/index.