Workspaces & Monorepos

Workspaces do npm vinculam pacotes internos em um único repositório para que o código compartilhado seja enviado sem a necessidade de publicar em um registro a cada alteração.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

{
  "name": "@acme/platform",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "npm run build -w @acme/shared && npm run build -w @acme/api"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": {
    "@acme/shared": "workspace:*"
  }
}

Quando usar isso:

• Múltiplos serviços implantáveis compartilham tipos ou utilitários TypeScript.
• Você deseja um único package-lock.json e um único npm ci para toda a fatia da organização.
• Pacotes internos são alterados no mesmo PR que seus consumidores.

Exemplo de Trabalho

platform/
  package.json          # raiz dos workspaces
  package-lock.json
  apps/
    api/
      package.json      # @acme/api
      src/server.ts
  packages/
    shared/
      package.json      # @acme/shared
      src/index.ts

// packages/shared/package.json
{
  "name": "@acme/shared",
  "version": "0.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}

// apps/api/src/server.ts
import { createLogger } from "@acme/shared";
 
const log = createLogger("api");
log.info("listening");

npm install          # vincula os workspaces
npm run build -w @acme/shared
npm run dev -w @acme/api

O que isso demonstra:

• workspace:* informa ao npm para criar um link simbólico (symlink) para o pacote local @acme/shared.
• -w direciona para um único workspace sem precisar usar cd.
• O pacote compartilhado é compilado antes que a API importe a saída compilada.

Mergulho Profundo

Como Funciona

• Os globs workspaces na raiz descobrem os arquivos package.json em apps/* e packages/*.
• npm install eleva (hoists) dependências compartilhadas e cria links simbólicos (symlinks) dos pacotes internos para o diretório node_modules do consumidor.
• O workspace:* é resolvido para a versão local no momento da instalação; a publicação o substitui pela versão semântica concreta.
• Um único package-lock.json na raiz captura todo o grafo de dependências.

Protocolo workspace:

Notas do TypeScript

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

• Habilite composite para referências de projeto entre pacotes.
• Consumidores devem importar pelos nomes dos pacotes (@acme/shared), não por caminhos relativos dentro de packages/shared/src.

Armadilhas

• Importar caminhos de origem entre pacotes - Ignora os limites do pacote e quebra a publicação. Correção: exportar através do main/exports do package.json.
• Esquecer de compilar bibliotecas compartilhadas - A API é executada com um dist/ desatualizado. Correção: ordene os scripts de build ou use dependências de pipeline do Turborepo.
• Dependências fantasmas - O hoisting permite importar pacotes não declarados. Correção: considere usar pnpm ou o ESLint import-x/no-extraneous-dependencies.
• Pacotes internos com versão 0.0.0 - Funciona para monorepos privados; bibliotecas publicáveis precisam de semver real antes de npm publish. Correção: execute npm version no pacote antes do lançamento externo.
• Dependências circulares de workspace - @acme/a depende de @acme/b e vice-versa. Correção: extraia o núcleo compartilhado para @acme/core.

Alternativas

FAQs

npm run test -w @acme/api
npm run build --workspaces --if-present

npm install zod -w @acme/api

Relacionados

• Noções Básicas de Gerenciadores de Pacotes - pnpm vs npm para monorepos
• Turborepo para Node - builds de workspace com cache
• Monorepo Multi-Serviço - limites de serviço

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.