Workspace

Quando você cria um novo workspace com @aws/nx-plugin, o gerador de preset configura um monorepo Nx com padrões sensatos para construir na AWS.

Criando um Workspace

pnpm

pnpm create @aws/nx-workspace my-project

yarn

yarn create @aws/nx-workspace my-project

npm

npm create @aws/nx-workspace -- my-project

bun

bun create @aws/nx-workspace my-project

Opções

Parâmetro	Tipo	Padrão	Descrição
iac	cdk | terraform	cdk	O provedor de IaC preferido.
gitSecrets	boolean	true	Se deve configurar git-secrets para prevenir o commit de credenciais AWS.
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).
module	esm | cjs	esm	Formato de módulo para código TypeScript e configuração gerados.
catalog	boolean	true	Se os geradores registram as versões de dependências no catálogo do gerenciador de pacotes (pnpm/yarn/bun), mantendo uma única fonte de verdade para versões. Quando false, as dependências são escritas diretamente no package.json de cada projeto e manter as versões alinhadas é sua responsabilidade.
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 executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Estrutura do Workspace

• Directorypackages/ Seus projetos ficam aqui

  • …
• package.json package.json raiz para seu monorepo
• nx.json Configuração do Nx (targets comuns, geradores de sincronização, caching)
• tsconfig.base.json Configuração raiz do TypeScript
• aws-nx-plugin.config.mts Configuração do Nx Plugin for AWS
• Directory.git-secrets/ Script bash do git-secrets vendorizado para verificação de credenciais

  • …
• Directory.husky/ Hooks do Git

  • …
• .mcp.json Configuração do servidor MCP do Nx Plugin for AWS para Claude Code
• .cursor/mcp.json …e para Cursor
• .kiro/settings/mcp.json …e para Kiro
• .gemini/settings.json …e para Gemini CLI
• .vscode/mcp.json …e para GitHub Copilot
• .codex/config.toml …e para OpenAI Codex

Nx

Nx é um sistema de build agnóstico de linguagem para monorepos, gerenciando dependências entre projetos escritos em qualquer linguagem de programação e as tarefas para construí-los. Você pode aprender mais no site do Nx.

Projetos

Um monorepo Nx é composto por um ou mais projetos, cada um com um arquivo project.json. O project.json define as tarefas de um projeto, conhecidas como targets, que definem como um projeto é construído, executado localmente, testado, etc. Ele também define dependências entre targets dentro ou entre projetos.

Por exemplo, um project.json pode definir um target build que depende de todos os projetos upstream serem construídos primeiro:

packages/my-project/project.json

{
  "name": "@my-workspace/my-project",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"]
    },
    "test": {
      "command": "vitest run"
    }
  }
}

Dica

Para projetos em linguagens não diretamente suportadas pelo Nx Plugin for AWS, você pode frequentemente encontrar um gerador no Nx Plugin Registry para ajudar. No entanto, é simples adicionar um projeto de qualquer linguagem ao seu monorepo — basta adicionar um arquivo project.json e definir seu target build para executar o comando de build específico para um projeto daquela linguagem.

Para detalhes sobre como projetos TypeScript e Python são configurados, consulte os guias dos geradores ts#project e py#project.

Caching

Nx armazena em cache a saída de targets executados anteriormente e os reproduz quando as entradas não mudaram. Isso acelera dramaticamente builds, testes e linting — especialmente em CI. Se você encontrar comportamento obsoleto ou inesperado, redefina o cache com:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Para mais detalhes, consulte a documentação de caching do Nx.

Política de Versão Única

A configuração padrão do monorepo usa uma política de versão única para projetos baseados em Node e Python.

Isso significa que todos os projetos dentro do seu monorepo usam a mesma versão de dependências por padrão, reduzindo problemas relacionados a pacotes no mesmo monorepo encontrando problemas de incompatibilidade de versão.

De uma perspectiva Node, isso significa um único lockfile na raiz, com dependências instaladas uma vez e vinculadas a cada projeto. Cada projeto Node declara as dependências de runtime que seu código-fonte importa em seu próprio package.json, enquanto ferramentas compartilhadas de build/teste ficam no devDependencies do package.json raiz. Adicione uma dependência de runtime de um projeto instalando-a nesse projeto:

pnpm

pnpm add some-npm-package --filter my-project

yarn

yarn workspace @my-scope/my-project add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-project

bun

bun add some-npm-package --cwd packages/my-project

Para gerenciadores de pacotes com suporte a catálogo (pnpm, yarn e bun), as versões de dependências são registradas no catálogo e referenciadas com o protocolo catalog:, mantendo uma única fonte de verdade para versões em todos os package.json dos projetos. Para npm workspaces, recomendamos syncpack para alinhar versões declaradas em múltiplos arquivos package.json.

De uma perspectiva Python, isso significa um único .venv na raiz do monorepo com todas as dependências instaladas nele. Cada projeto Python tem seu próprio pyproject.toml, mas as versões dessas dependências são gerenciadas pelo workspace UV e subsequentemente escritas no arquivo uv.lock na raiz.

Comandos Comuns

Build

Construir todos os projetos no workspace:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint

Fazer lint e corrigir automaticamente todos os projetos:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

Executar testes em todos os projetos:

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Inicie todos os servidores de desenvolvimento locais em seu workspace:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Consulte o guia Desenvolvimento Local para mais detalhes.

Sync

Execute quaisquer geradores de sincronização, que por exemplo sincronizam referências de projeto TypeScript (consulte o guia do gerador ts#project para mais detalhes):

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Executar Targets Específicos

Você pode executar targets específicos para projetos específicos com:

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

Por exemplo:

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

Isso executará o target escolhido, bem como os targets dos quais ele depende.

O Que Está Incluído

Linting

Novos workspaces são configurados com Biome para análise estática e formatação de código. Executar lint verifica problemas em todos os projetos, e lint --configuration=fix os corrige automaticamente.

Git Secrets

Novos workspaces incluem hooks de pré-commit do git-secrets que verificam arquivos preparados em busca de padrões de credenciais AWS antes de cada commit. Isso previne o commit acidental de chaves de acesso, chaves secretas e outros valores sensíveis.

Suprimindo Falsos Positivos

Padrões no git-secrets usam expressões regulares compatíveis com egrep. Se o git-secrets bloquear um commit que não contém credenciais reais:

# Permitir um padrão regex específico
git secrets --add --allowed 'my-regex-pattern'

# Permitir uma string literal (caracteres especiais são escapados)
git secrets --add --allowed --literal 'my-literal+string'

Você também pode criar um arquivo .gitallowed na raiz do repositório com uma regex compatível com egrep por linha (compartilhado com sua equipe via controle de versão):

.gitallowed

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

Para detalhes completos sobre gerenciamento de padrões, consulte a documentação do git-secrets.

Configuração do Nx Plugin for AWS

O workspace vem com um arquivo aws-nx-plugin.config.mts na raiz. Os geradores leem este arquivo para escolher padrões sensatos, para que você não precise passar as mesmas flags toda vez. Duas configurações são particularmente úteis:

// aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: {
    provider: 'CDK', // or 'Terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
} satisfies AwsNxPluginConfig;

• iac.provider — o provedor de infraestrutura como código padrão (CDK ou Terraform) usado por geradores que emitem infraestrutura (por exemplo, ts#infra, ts#api, py#api). Geradores que aceitam uma flag --iac têm como padrão Inherit, que lê este valor.
• containers.engine — a CLI de contêiner (docker ou finch) incorporada nos comandos de build/push/login gerados. Builds de image-asset do CDK também capturam isso através da variável de ambiente CDK_DOCKER. Consulte o guia de bundling Docker para detalhes.

Você pode editar qualquer uma das configurações a qualquer momento — execuções subsequentes do gerador irão capturar o novo valor.