Nx no Node.js

O Nx no Node.js oferece um sistema de projetos, tarefas, cache, geração de código e análise de dependências para monorepos. Ele pode ser adicionado a um repositório existente com npm Workspaces ou usado para criar uma estrutura completa com aplicações, bibliotecas e plugins.

O diferencial do Nx é combinar project graph, task graph, comandos affected, plugins que inferem tarefas e recursos de CI distribuída. Essa potência exige disciplina: projetos precisam ter limites claros, inputs e outputs corretos, tags de arquitetura e migrações controladas.

Neste guia, você aprenderá a instalar Nx, registrar projetos Node.js, executar tarefas, configurar pipelines, cache, affected, module boundaries, generators, Nx Cloud e CI.

Quando usar Nx?

Nx é útil quando o repositório possui:

• muitas aplicações e bibliotecas;
• dependências internas complexas;
• necessidade de tarefas affected;
• geradores padronizados;
• plugins para Node, Nest, Vite ou Jest;
• cache local e remoto;
• regras de arquitetura;
• CI que precisa escalar.

Para poucos pacotes e scripts simples, npm Workspaces ou Turborepo podem ser suficientes.

Adicionando Nx ao repositório

npx nx@latest init

O comando detecta gerenciador, scripts e estrutura. Revise cada alteração antes de confirmar.

Criando um workspace novo

npx create-nx-workspace@latest

Escolha package manager, stack e estratégia de CI. Para controle, comece com uma configuração mínima e adicione plugins quando necessários.

Estrutura

workspace/
├── apps/
│   ├── api/
│   └── worker/
├── libs/
│   ├── domain/
│   ├── database/
│   └── observability/
├── nx.json
├── package.json
└── tsconfig.base.json

Workspaces continuam importantes

Nx não substitui o gerenciador de pacotes. O package.json raiz pode usar:

{
  "private": true,
  "workspaces": ["apps/*", "libs/*"]
}

Veja npm Workspaces no Node.js.

Projetos e targets

Um projeto pode ser definido em project.json:

{
  "name": "api",
  "root": "apps/api",
  "sourceRoot": "apps/api/src",
  "projectType": "application",
  "targets": {
    "build": {
      "command": "tsc -p apps/api/tsconfig.build.json",
      "outputs": ["{workspaceRoot}/dist/apps/api"]
    },
    "test": {
      "command": "node --test apps/api/test/**/*.test.js"
    }
  }
}

Tarefas inferidas

Plugins conseguem detectar arquivos como vite.config.ts, eslint.config.js e configurações de teste para criar targets automaticamente. A documentação de execução de tarefas no Nx explica scripts, project.json e tarefas inferidas.

Executando uma tarefa

npx nx build api
npx nx test domain
npx nx lint worker

Run many

npx nx run-many -t build lint test

Para projetos específicos:

npx nx run-many -t build test -p api worker

Nx paraleliza quando o grafo permite.

Task pipeline

No nx.json:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "cache": true
    }
  }
}

^build executa build das dependências antes do projeto atual.

Outputs

"outputs": [
  "{workspaceRoot}/dist/{projectRoot}"
]

Outputs corretos são essenciais para cache. Inclua JavaScript, declarations, coverage e outros artefatos realmente usados.

Inputs nomeados

{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.test.ts",
      "!{projectRoot}/test/**/*"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"]
    }
  }
}

Evite globais excessivos que invalidam todo cache a cada mudança.

Cache local

Nx calcula um hash com fontes, configuração, dependências, runtime e ambiente declarado. Se nada mudou, restaura o resultado.

npx nx build api

Execute novamente para observar o cache.

Forçando execução

npx nx build api --skip-nx-cache

Use para diagnosticar cache incorreto. Se o resultado muda, revise inputs e outputs.

Affected

npx nx affected -t lint test build \
  --base=origin/main \
  --head=HEAD

Nx usa o project graph e mudanças Git para executar somente projetos afetados, incluindo dependentes.

Histórico Git no CI

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

Sem a base de comparação, affected pode selecionar incorretamente ou exigir fallback.

Project graph

npx nx graph

O gráfico ajuda a detectar ciclos, dependências inesperadas e bibliotecas centrais demais.

Tags

No project.json:

{
  "tags": ["type:app", "scope:orders", "layer:api"]
}

Tags permitem regras de arquitetura.

Module boundaries

Com a regra ESLint do Nx:

"@nx/enforce-module-boundaries": [
  "error",
  {
    "depConstraints": [
      {
        "sourceTag": "layer:domain",
        "onlyDependOnLibsWithTags": ["layer:domain"]
      },
      {
        "sourceTag": "layer:api",
        "onlyDependOnLibsWithTags": [
          "layer:api",
          "layer:application",
          "layer:domain"
        ]
      }
    ]
  }
]

Isso evita que domínio importe infraestrutura ou que uma feature acesse internals de outra.

Consulte ESLint Flat Config no Node.js.

Generators

npx nx generate @nx/node:application api
npx nx generate @nx/js:library domain

Generators criam arquivos e atualizam configuração. Revise o dry run:

npx nx generate @nx/js:library pricing --dry-run

Generator próprio

Organizações podem criar plugin interno para gerar módulos, handlers e testes padronizados. Use para decisões repetitivas, não para esconder arquitetura em templates enormes.

Plugin Node.js

Plugins do Nx podem criar aplicações, configurar build e inferir targets. Fixe versões alinhadas ao core e execute migrations oficiais durante upgrades.

Executors

Executors encapsulam comandos e opções. Para tarefas simples, command é suficiente. Use executor quando precisa de API, validação ou integração reutilizável.

Root tasks

Scripts da raiz podem entrar no pipeline:

{
  "name": "workspace-root",
  "scripts": {
    "docs": "nx exec -- node scripts/docs.js"
  },
  "nx": {}
}

Tarefas persistentes

Servidores de desenvolvimento devem ser não cacheáveis e contínuos conforme a configuração da versão. Não coloque deploy ou migration em cache.

Nx Cloud

Nx Cloud oferece remote cache, distribuição, detecção de flaky tests e outros recursos. Avalie:

• localização dos dados;
• criptografia;
• retenção;
• controle de acesso;
• segredos nos artifacts;
• dependência do serviço.

CI com GitHub Actions

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm

- run: npm ci
- run: npx nx affected -t lint typecheck test build \
    --base=origin/main \
    --head=HEAD

Veja CI para Node.js com GitHub Actions.

Distribuição de tarefas

Em repositórios grandes, tarefas podem ser distribuídas entre agentes. Isso reduz duração total, mas exige outputs determinísticos e isolamento de recursos.

Testes flaky

Repetir automaticamente um teste pode reduzir ruído, mas também esconder falhas reais. Registre flakiness, atribua responsável e corrija a causa.

Releases

Nx Release pode versionar projetos, gerar changelogs e publicar. Compare com Changesets no Node.js e semantic-release no Node.js.

Docker

Construa apenas a aplicação alvo e suas dependências. Use project graph para reduzir contexto, mas teste a imagem final. Consulte Docker Multi-stage para Node.js.

Migrations do Nx

npx nx migrate latest
npm install
npx nx migrate --run-migrations

Faça upgrade em branch dedicada, revise migrations e execute CI completa.

Daemon

Nx usa processo daemon para acelerar análise local. Em CI, o comportamento pode ser diferente. Se houver inconsistência, diagnostique com logs e desative temporariamente, não como solução permanente.

Comparação com Turborepo

Turborepo no Node.js é centrado em scripts, task graph e cache. Nx adiciona project graph, plugins, generators, module boundaries e recursos de plataforma. A escolha depende da complexidade que precisa ser gerenciada.

Erros comuns

• Projeto sem boundaries: qualquer biblioteca importa qualquer coisa.
• Outputs ausentes: cache incompleto.
• Inputs globais demais: tudo invalida.
• Affected sem base correta: mudanças são ignoradas.
• Generator sem revisão: boilerplate desnecessário.
• Plugin desalinhado: migrations falham.
• Cache de efeitos externos: deploy é pulado.
• Remote cache com secrets: dados vazam.

Configuração recomendada

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.test.ts",
      "!{projectRoot}/test/**/*"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "cache": true
    },
    "lint": {
      "cache": true
    }
  }
}

Conclusão

O Nx no Node.js combina task graph e cache com uma visão explícita dos projetos e dependências. Isso permite executar apenas o que foi afetado, impor fronteiras e padronizar geração de código.

Comece pequeno, declare outputs, use tags arquiteturais e revise plugins. Com CI e cache protegidos, Nx ajuda monorepos grandes a crescer sem perder previsibilidade.