Workspace

Quando você cria um novo workspace com @aws/nx-plugin, o gerador 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/ Your projects live here

  • …
• package.json Root package.json for your monorepo
• nx.json Nx configuration (common targets, sync generators, caching)
• tsconfig.base.json Root TypeScript configuration
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• Directory.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• Directory.husky/ Git hooks

  • …
• .mcp.json Nx Plugin for AWS MCP server configuration for Claude Code
• .cursor/mcp.json …and for Cursor
• .kiro/settings/mcp.json …and for Kiro
• .gemini/settings.json …and for Gemini CLI
• .vscode/mcp.json …and for GitHub Copilot
• .codex/config.toml …and for 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. É 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.

Cache

Nx faz cache da 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 cache 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/test ficam no devDependencies do package.json raiz. Adicione uma dependência de runtime de um projeto instalando-a naquele 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 cada package.json de cada projeto. 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 auto-corrigir 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

Iniciar todos os servidores de desenvolvimento local em seu workspace:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Consulte o guia de Desenvolvimento Local para mais detalhes.

Sync

Executar 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 todos os projetos em busca de problemas, e lint --configuration=fix os corrige automaticamente.

Git Secrets

Novos workspaces incluem hooks de pré-commit do git-secrets que escaneiam arquivos staged em busca de padrões de credenciais AWS antes de cada commit. Isso evita commitar acidentalmente 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:

# Allow a specific regex pattern
git secrets --add --allowed 'my-regex-pattern'

# Allow a literal string (special characters are escaped)
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 (compartilhada 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, então você não precisa 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 via a variável de ambiente CDK_DOCKER. Consulte o guia de bundling Docker para detalhes.

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