Claude Code e Nx Workspace: guia prático de monorepo
Use Claude Code com Nx Workspace para definir limites, nx graph, affected CI, cache e evitar monorepo exagerado.
Nx Workspace não é só um repositório grande
Se você pedir ao Claude Code “crie um monorepo”, ele provavelmente vai gerar muitos arquivos. O problema real aparece depois: uma mudança em apps/web afeta apps/admin? Um botão fica dentro da app ou em uma biblioteca UI compartilhada? O CI precisa rodar todos os testes em todo pull request?
Nx Workspace responde com project graph, task graph, comandos affected e cache. O modelo mental oficial do Nx explica como o Nx analisa projetos e executa apenas o trabalho necessário. Para iniciantes, pense no Nx como um mapa de dependências com um executor de tarefas.
Neste guia, Claude Code é revisor e par de implementação, não um gerador sem controle. Use como base a documentação oficial: create-nx-workspace, workspace generators, affected, CI setup e caching tasks. Para contexto, leia também gestão de monorepo com Claude Code, pnpm workspace e CI/CD setup.
Três casos em que Nx faz sentido
Nx é poderoso, mas não é necessário para todo projeto pequeno. Uma landing page e uma API simples podem ficar melhores em um repositório comum. Nx compensa quando limites e custo de verificação começam a pesar.
O primeiro caso é quando várias apps compartilham tipos ou UI. apps/web, apps/admin, apps/api, libs/contracts e libs/ui podem ficar juntos para atualizar tipos de API e componentes base em um único PR.
O segundo caso é CI seletivo. Se site de conteúdo, páginas de treinamento, admin e API compartilham um repositório, rodar tudo em cada PR fica caro. nx affected -t test build usa mudanças Git e o grafo de dependências para selecionar só projetos afetados.
O terceiro caso é tornar Claude Code mais seguro. Quando libs/ui é só UI, libs/contracts é API types, libs/config é configuração compartilhada e apps/* são apps deployáveis, Claude Code tem menos espaço para refatorar demais. Isso importa em páginas com AdSense, afiliados, formulários de consulta e CTAs de pagamento.
Se você ainda não consegue explicar os limites do repositório, comece por repo map first pass. Nx acelera uma estrutura clara; ele não conserta automaticamente uma arquitetura confusa.
Estrutura alvo
Vamos começar pequeno: duas apps React, uma API Node, uma biblioteca UI, uma biblioteca de contratos e uma biblioteca de configuração.
flowchart LR
web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
admin["apps/admin\nReact + Vite"] --> ui
web --> contracts["libs/contracts\nAPI types"]
admin --> contracts
api["apps/api\nNode API"] --> contracts
web --> config["libs/config\nlint/test config"]
api --> config
A regra é simples. apps/* são unidades executadas ou publicadas. libs/* são peças reutilizáveis. Uma biblioteca não deve importar de uma app. Uma biblioteca UI não lê variáveis de ambiente da API, e uma biblioteca de contratos não contém componentes React.
Passe os limites para Claude Code antes de editar:
Entenda primeiro este Nx Workspace. Ainda não edite arquivos.
Regras:
- apps/web e apps/admin são apps frontend
- apps/api é a API
- libs/ui contém apenas componentes UI reutilizáveis
- libs/contracts contém tipos de API e Zod schemas
- libs/config contém configuração compartilhada de ESLint, Vitest e TypeScript
- libs/* não deve importar de apps/*
Antes das mudanças, verifique nx graph. Depois, informe os comandos nx affected para validação.
Setup copiável
Os comandos assumem Node.js 20+, Git e pnpm. As opções são explícitas para evitar variações de prompts interativos.
npx create-nx-workspace@latest acme-nx \
--workspaceType=integrated \
--preset=apps \
--packageManager=pnpm \
--nxCloud=skip \
--interactive=false
cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node
Gere apps e bibliotecas com generators do Nx. Eles atualizam configuração Nx, paths TypeScript e metadados do projeto de forma consistente.
pnpm nx g @nx/react:app web \
--directory=apps/web \
--bundler=vite \
--unitTestRunner=vitest \
--e2eTestRunner=playwright \
--style=css
pnpm nx g @nx/react:app admin \
--directory=apps/admin \
--bundler=vite \
--unitTestRunner=vitest \
--e2eTestRunner=none \
--style=css
pnpm nx g @nx/node:app api \
--directory=apps/api \
--unitTestRunner=vitest
pnpm nx g @nx/react:lib ui \
--directory=libs/ui \
--unitTestRunner=vitest
pnpm nx g @nx/js:lib contracts \
--directory=libs/contracts \
--unitTestRunner=vitest
pnpm nx g @nx/js:lib config \
--directory=libs/config \
--unitTestRunner=none
Antes de editar, veja o resultado:
pnpm nx graph
pnpm nx show projects
pnpm nx show project web
Se o grafo já parece confuso, simplifique antes de criar mais bibliotecas.
Leia project.json antes de mudar
Para iniciantes, project.json é a lista de tarefas que um projeto sabe executar.
{
"name": "web",
"sourceRoot": "apps/web/src",
"projectType": "application",
"targets": {
"build": {
"executor": "@nx/vite:build",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/apps/web"
}
},
"test": {
"executor": "@nx/vite:test",
"outputs": ["{workspaceRoot}/coverage/apps/web"],
"options": {
"passWithNoTests": true
}
},
"serve": {
"executor": "@nx/vite:dev-server",
"options": {
"buildTarget": "web:build"
}
}
},
"tags": ["scope:app", "type:web"]
}
Peça explicação antes de permitir edição:
Leia apps/web/project.json e explique build, test e serve para uma pessoa iniciante.
Se precisar mudar algo, proponha apenas o menor diff.
Não quebre outputs, comportamento de cache nem relações dependsOn.
outputs é essencial porque o Nx usa esse campo para cache. Um caminho errado pode inutilizar o cache ou reutilizar artefatos antigos.
affected no CI
affected compara mudanças Git com o grafo de projetos e roda tarefas só onde pode haver impacto.
pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD
No GitHub Actions, busque o histórico completo para comparar branches. Rode tarefas via nx; chamadas diretas a vitest, eslint ou tsc ignoram affected e cache.
name: nx-ci
on:
pull_request:
push:
branches: [main]
jobs:
affected:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v4
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3
Em times, Nx Cloud pode reduzir trabalho repetido no CI. Primeiro prove valor com cache local e affected; depois adicione cache remoto se o tempo de CI virar gargalo.
Erros comuns
O primeiro erro é criar libs/shared e colocar tudo ali. Antes de mover código, peça ao Claude Code para classificar como UI, contracts, config ou utilitário puro.
O segundo é importar apps/* dentro de libs/*. Isso inverte a dependência e dificulta reutilização.
O terceiro é rodar ferramentas cruas no CI. Prefira pnpm nx run-many -t test ou pnpm nx affected -t test.
O quarto é exagerar na primeira semana. Não crie libs/auth, libs/domain e libs/data-access antes de existir duplicação real.
O quinto é deixar Claude Code editar sem contexto de graph. Inclua pnpm nx graph antes e pnpm nx affected -t test build depois.
Monetização: proteja páginas que geram receita
Em um site como ClaudeCodeLab, artigos, páginas de treinamento, admin, formulários e analytics podem compartilhar um repositório. Nx ajuda não só na velocidade, mas em explicar se uma página de receita foi afetada. Se libs/cta muda, o grafo mostra quais páginas revisar. Se libs/analytics muda, affected CI mostra quais apps precisam de smoke test.
Isso vale para layouts de AdSense, blocos de afiliado, CTAs de checkout e formulários de consulta. Para padronizar Claude Code e monorepos em equipe, veja ClaudeCodeLab training. Se você trabalha sozinho, crie este workspace e salve uma captura de nx graph antes de adicionar mais packages.
Verificação prática
No meu teste como Masa, criei primeiro apenas web, admin, api, ui e contracts. Ao mudar um tipo em libs/contracts, pnpm nx affected -t test build --base=main --head=HEAD selecionou as apps dependentes de contracts. Ao mudar só libs/ui, o build da API ficou fora. A lição não foi decorar opções do Nx, mas tornar graph e limites visíveis antes de pedir alterações ao Claude Code.
Resumo
Nx Workspace não serve para deixar o repositório enorme. Ele torna dependências visíveis, verifica só projetos afetados e dá limites claros ao Claude Code.
Comece pequeno, leia project.json, inspecione nx graph e coloque nx affected no CI. Assim, Claude Code deixa de ser só um gerador de arquivos e vira um revisor útil da estrutura do monorepo.
Artigos relacionados
Claude Code e Turborepo: guia prático para monorepos
Planeje um monorepo Turborepo com Claude Code: tasks, cache, CI, prompts e erros comuns.
Gerenciar monorepos com Claude Code: pnpm, Turborepo, Nx e CI
Guia prático para monorepos com Claude Code: mapa do repositório, pnpm workspace, affected tasks, CODEOWNERS e CI.
Monorepo prático com Claude Code e pnpm workspace
Monte um monorepo pequeno com Claude Code e pnpm workspace: dependências, filter, CI e armadilhas comuns.
PDF grátis: cheatsheet do Claude Code
Informe seu e-mail e baixe uma página com comandos, hábitos de revisão e workflows seguros.
Cuidamos dos seus dados e não enviamos spam.
Sobre o autor
Masa
Engenheiro focado em workflows práticos com Claude Code.