Adicionar a um Projeto Existente

Nem todo projeto começa com pnpm create @aws/nx-workspace. Se você já tem um workspace Nx — ou um monorepo ao qual você pode adicionar Nx — você pode adotar @aws/nx-plugin incrementalmente sem recriar seu projeto.

Pré-requisitos

Requeridos

Git
Node >= 22 (Recomendamos usar algo como NVM para gerenciar suas versões do Node)
- verifique executando node --version
PNPM >= 11 (você também pode usar Yarn >= 4, Bun >= 1 ou NPM >= 10 se preferir)
- verifique executando pnpm --version, yarn --version, bun --version ou npm --version
UV >= 0.5.29
1. instale o Python 3.14 executando: uv python install 3.14.0
2. verifique com uv python list --only-installed
Credenciais AWS configuradas para sua conta AWS de destino (onde sua aplicação será implantada)

Adicionando Nx a um projeto não-Nx

Se seu projeto ainda não usa Nx, adicione-o primeiro com nx init. Este é um passo que o próprio Nx possui; o plugin se baseia em um workspace Nx funcional. Funciona em um pacote simples, um workspace npm/pnpm/yarn/bun, um Turborepo ou um monorepo Lerna:

pnpm dlx nx@23.0.2 init

yarn dlx nx@23.0.2 init

npx nx@23.0.2 init

bunx nx@23.0.2 init

Siga os prompts para adicionar Nx ao seu workspace. Para mais detalhes, consulte a Documentação do Nx.

pnpm executa apenas scripts de instalação para pacotes na lista de permissões, e nx precisa de seu script de instalação — sem ele, a instalação que nx init realiza pode falhar, deixando um placeholder set this to true or false em pnpm-workspace.yaml. Adicione-o à lista de permissões antes de executar nx init:

allowBuilds:
  - nx

Projetos não-Node (Python, Go, Java, Rust, …)

Nx e o plugin são distribuídos como pacotes npm, então um projeto sem ferramentas Node.js precisa de um package.json raiz mínimo antes que nx init possa fazer algo útil:

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

Crie esse arquivo, então execute nx init e adicione o plugin como de costume. Suas ferramentas de linguagem existentes não são tocadas — projetos Nx gerados pelo plugin (incluindo projetos Python) vivem ao lado do seu código existente, e você pode conectar seu build existente ao Nx incrementalmente.

Projetos de pacote único

O plugin é projetado para monorepos — ele gera cada projeto em seu próprio diretório sob packages/. Se você está começando de um projeto de pacote único (um package.json na raiz com seu código-fonte diretamente abaixo dele, sem workspaces), mova seu pacote existente para packages/ antes de adotar o plugin para que seu projeto fique ao lado dos que o plugin gera:

Crie um diretório packages/<seu-pacote>/ e mova seu código-fonte, package.json e tsconfig.json para ele.
Crie um novo package.json raiz que atua como o manifesto do workspace em vez de um projeto em si:
package.json
```
{
  "name": "<seu-workspace>",
  "private": true,
  "type": "module"
}
```
Declare o workspace para que seu gerenciador de pacotes descubra projetos sob packages/. Para pnpm, adicione um pnpm-workspace.yaml:
pnpm-workspace.yaml
```
packages:
  - packages/*
```
Para npm/yarn/bun, adicione um campo workspaces ao package.json raiz em vez disso:
package.json
```
{
  "workspaces": ["packages/*"]
}
```
Execute nx init (se ainda não o fez), então adicione o plugin.

Adicionando o plugin

Use nx add, que instala o plugin em uma versão compatível com sua instalação do Nx e então executa seu gerador init para configurar seu workspace:

pnpm nx add @aws/nx-plugin

yarn nx add @aws/nx-plugin

npx nx add @aws/nx-plugin

bunx nx add @aws/nx-plugin

Uma vez concluído, seu workspace está pronto — escolha os geradores que você precisa e comece a gerar projetos.

O que este gerador configura

Adicionar o plugin faz as mudanças determinísticas que um workspace precisa para executar os geradores do plugin. Ele preserva o formato de módulo do seu workspace: um workspace cujo package.json raiz tem type: "module" permanece ESM, qualquer outra coisa permanece CommonJS, e o código gerado segue o mesmo padrão. Ele não sobrescreve arquivos existentes, e você pode precisar fazer algumas mudanças manuais após esta etapa, dependendo da sua configuração existente.

Ele cria ou atualiza os seguintes arquivos:

aws-nx-plugin.config.mts registra seu provedor IaC escolhido (CDK ou Terraform) e motor de contêiner; os geradores leem iac.provider daqui
nx.json registra os geradores de sincronização (@nx/js:typescript-sync e @aws/nx-plugin:ts#sync) no target compile para que as referências de projeto TypeScript permaneçam sincronizadas
tsconfig.json uma configuração TypeScript raiz referenciando os projetos do seu workspace, que a sincronização TypeScript do Nx mantém atualizada
tsconfig.base.json as opções de compilador compartilhadas que os projetos TypeScript do plugin estendem (veja abaixo o que ele carrega)
pnpm-workspace.yaml (apenas pnpm) adiciona à lista de permissões os scripts de build que as dependências do plugin precisam (@swc/core, esbuild, nx, sharp)
package.json scripts de conveniência para tarefas comuns, além das devDependencies nx, @nx/js, @nx/workspace, typescript e Biome
biome.json configuração padrão de formatador e linter do Biome
.mcp.json configura o servidor MCP para agentes de codificação suportados a menos que desabilitado (também equivalentes .cursor/, .kiro/, .gemini/, .vscode/ e .codex/)

A configuração do servidor MCP pode ser desabilitada com --mcp=false.

Clique aqui para ver as opções do compilador que um tsconfig.base.json criado carrega.

Opções

Parâmetro	Tipo	Padrão	Descrição
iac	cdk \| terraform	cdk	O provedor de IaC preferido.
mcp	boolean	true	Se deve configurar o Nx Plugin para servidor AWS MCP para uso por agentes de codificação.
containers	infer \| docker \| finch	infer	O motor de contêineres a ser usado para build/push/login. 'infer' escolhe docker se instalado, caso contrário finch (voltando para docker quando nenhum estiver instalado).
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao agrupar múltiplos geradores (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Solução de problemas

`The workspace is out of sync`

As referências de projeto TypeScript precisam de sincronização. init registra os geradores de sincronização; execute:

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

`ERR_PNPM_IGNORED_BUILDS` durante a instalação

pnpm pula scripts de instalação para pacotes que não estão na lista de permissões. init adiciona à lista de permissões os que as ferramentas do plugin precisam (@swc/core, esbuild, nx, sharp) em pnpm-workspace.yaml, mas o bloqueio pode disparar durante nx add @aws/nx-plugin em si — antes que init tenha sido executado. Execute pnpm approve-builds e aprove os pacotes listados (ou adicione-os sob allowBuilds:), então execute novamente a instalação.

`nx sync` trava, ou `plugin worker ... exited before the connection was established`

Se duas versões diferentes de nx estiverem presentes na mesma árvore node_modules (execute npm ls nx para confirmar), seu IPC de plugin-worker entra em deadlock. O gerador init fixa a devDependency nx raiz na versão que os próprios pacotes @nx/* do plugin resolvem, mas uma instalação posterior de outro pacote @nx/* em uma versão de patch diferente pode reintroduzir a incompatibilidade. Alinhe cada entrada nx e @nx/* em seu package.json raiz a uma única versão e reinstale.

`ts.readConfigFile is not a function`

Seu workspace tem TypeScript 7 instalado, que o Nx ainda não suporta — os plugins do Nx dependem da API do compilador em processo do TypeScript, que o TypeScript 7 não fornece mais. Fixe typescript em seu package.json raiz na versão que o plugin usa (o gerador init instala uma versão compatível) e reinstale.

`Recursive task invocation detected`

Seu package.json raiz está registrado como um projeto Nx (ele tem uma chave "nx", que nx init adiciona para um repositório de pacote único) e carrega um script build de nx run-many --target build. O Nx então infere um target build na raiz que chama a si mesmo. Mova seu código-fonte para packages/<seu-pacote>/ para que a raiz se torne um manifesto de workspace em vez de um projeto — veja Projetos de pacote único. (Os próprios presets standalone do Nx evitam isso definindo "nx": { "includedScripts": [] } no pacote raiz; você pode fazer o mesmo como uma alternativa mais rápida.)

Erros TypeScript em seus projetos existentes após adicionar o plugin (`TS6059`, `TS7016`, `TS5011`, `NG4006`)

Os próprios projetos gerados pelo plugin carregam as configurações TypeScript de que precisam em seu tsconfig.lib.json por projeto, então eles constroem independentemente do seu tsconfig.base.json. Esses erros aparecem em vez disso em um projeto pré-existente seu que herda um tsconfig.base.json que init criou (com composite/emitDeclarationOnly/nodenext) mas não é compatível com essas configurações — por exemplo, o compilador Angular rejeita emitDeclarationOnly (NG4006), ou um projeto que define outDir sem um rootDir agora precisa de um (TS5011). Adicione sobrescritas de tsconfig por projeto redeclarando as opções conflitantes para esses projetos (por exemplo, "rootDir": "src"), ou aponte os projetos do plugin e seus projetos para configurações base separadas.

init nunca reescreve um tsconfig.base.json existente, precisamente para que não possa quebrar silenciosamente os projetos que herdam dele — resolver essas incompatibilidades é uma decisão que apenas você pode tomar para sua base de código.