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.
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.
Artigos relacionados
Workflow Obsidian para CLAUDE.md com Claude Code
Transforme notas de trabalho do Obsidian em notas operacionais CLAUDE.md para preservar contexto.
Claude Code Revenue CTA Routing: artigos para PDF, Gumroad e consultoria
Um fluxo com Claude Code para levar leitores ao PDF grátis, Gumroad ou consultoria conforme intenção.
Regras de handoff para equipes com Claude Code: evidências, permissões, rollback e receita
Formato prático para entregar trabalho do Claude Code com prova, permissões, rollback, PDF grátis, Gumroad e consultoria.