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
addTsPlugin	boolean	true	Se deve adicionar o plugin ts.
iacProvider	string	CDK	O provedor de IaC preferido.
gitSecrets	boolean	true	Se deve configurar git-secrets para prevenir o commit de credenciais AWS.
containerEngine	string	infer	O motor de contêiner a ser usado para build/push/login. 'infer' escolhe docker se instalado, caso contrário finch (voltando para docker quando nenhum estiver instalado).

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

  • …

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 um único node_modules contendo todas as dependências. Se você precisar adicionar uma nova dependência, adicione-a no package.json raiz.

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

Se você tem um website, inicie-o e todos os componentes conectados localmente:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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 ESLint para análise estática e Prettier para formatação de código. Executar lint aplica ambos a todos os projetos.

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#trpc-api, py#fast-api). Geradores que aceitam uma flag --iacProvider 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.