Workspace

Quando crei un nuovo workspace con @aws/nx-plugin, il generatore preset configura un monorepo Nx con impostazioni predefinite sensate per costruire su AWS.

Creare un 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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
iac	cdk | terraform	cdk	Il provider IaC preferito.
gitSecrets	boolean	true	Se configurare git-secrets per impedire il commit di credenziali AWS.
mcp	boolean	true	Se configurare il Plugin Nx per il server AWS MCP per l'uso da parte di agenti di codifica.
containers	infer | docker | finch	infer	Il motore di container da utilizzare per build/push/login. 'infer' seleziona docker se installato, altrimenti finch (con fallback a docker quando nessuno dei due è installato).
module	esm | cjs	esm	Formato del modulo per il codice TypeScript e la configurazione generati.
catalog	boolean	true	Se i generatori registrano le versioni delle dipendenze nel catalogo del package manager (pnpm/yarn/bun), mantenendo un'unica fonte di verità per le versioni. Quando false, le dipendenze vengono scritte direttamente nel package.json di ciascun progetto e mantenere le versioni allineate è una tua responsabilità.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Struttura del 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 è un sistema di build indipendente dal linguaggio per monorepo, che gestisce le dipendenze tra progetti scritti in qualsiasi linguaggio di programmazione e le attività per costruirli. Puoi saperne di più sul sito web di Nx.

Progetti

Un monorepo Nx è composto da uno o più progetti, ciascuno con un file project.json. Il project.json definisce le attività di un progetto, note come target, che definiscono come un progetto viene costruito, eseguito localmente, testato, ecc. Definisce anche le dipendenze tra target all’interno o tra progetti.

Ad esempio, un project.json potrebbe definire un target build che dipende dalla costruzione preventiva di tutti i progetti upstream:

packages/my-project/project.json

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

Consiglio

Per i progetti in linguaggi non direttamente supportati da Nx Plugin for AWS, puoi spesso trovare un generatore nel Nx Plugin Registry per aiutarti. È comunque semplice aggiungere un progetto di qualsiasi linguaggio al tuo monorepo — basta aggiungere un file project.json e definire il suo target build per eseguire il comando di build specifico per un progetto di quel linguaggio.

Per i dettagli su come vengono configurati i progetti TypeScript e Python, consulta le guide dei generatori ts#project e py#project.

Caching

Nx memorizza nella cache l’output dei target eseguiti in precedenza e li riproduce quando gli input non sono cambiati. Questo velocizza notevolmente build, test e linting — specialmente in CI. Se riscontri comportamenti obsoleti o inaspettati, reimposta la cache con:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Per maggiori dettagli, consulta la documentazione sul caching di Nx.

Single Version Policy

La configurazione predefinita del monorepo utilizza una single version policy sia per i progetti basati su Node che su Python.

Ciò significa che tutti i progetti all’interno del tuo monorepo utilizzano la stessa versione delle dipendenze per impostazione predefinita, riducendo i problemi relativi ai pacchetti nello stesso monorepo che incontrano problemi di disallineamento delle versioni.

Dal punto di vista di Node, questo significa un singolo lockfile alla radice, con le dipendenze installate una volta e collegate in ogni progetto. Ogni progetto Node dichiara le dipendenze runtime che il suo codice sorgente importa nel proprio package.json, mentre gli strumenti di build/test condivisi risiedono nelle devDependencies del package.json radice. Aggiungi una dipendenza runtime di un progetto installandola in quel progetto:

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

Per i package manager con supporto per i catalog (pnpm, yarn e bun), le versioni delle dipendenze vengono registrate nel catalog e referenziate con il protocollo catalog:, mantenendo un’unica fonte di verità per le versioni in ogni package.json del progetto. Per npm workspaces, raccomandiamo syncpack per allineare le versioni dichiarate in più file package.json.

Dal punto di vista di Python, questo significa un singolo .venv alla radice del monorepo con tutte le dipendenze installate al suo interno. Ogni progetto Python ha il proprio pyproject.toml, ma le versioni di quelle dipendenze sono gestite dal workspace UV e successivamente scritte nel file uv.lock alla radice.

Comandi Comuni

Build

Costruisci tutti i progetti nel workspace:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint

Esegui il lint e correggi automaticamente tutti i progetti:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

Esegui i test su tutti i progetti:

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Avvia tutti i server di sviluppo locali nel tuo workspace:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Consulta la guida Sviluppo Locale per maggiori dettagli.

Sync

Esegui qualsiasi sync generator, che ad esempio sincronizzano i riferimenti ai progetti TypeScript (consulta la guida del generatore ts#project per maggiori dettagli):

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Eseguire Target Specifici

Puoi eseguire target specifici per progetti specifici con:

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

Ad esempio:

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

Questo eseguirà il target scelto così come i target da cui dipende.

Cosa è Incluso

Linting

I nuovi workspace sono configurati con Biome per l’analisi statica e la formattazione del codice. L’esecuzione di lint controlla tutti i progetti per problemi, e lint --configuration=fix li corregge automaticamente.

Git Secrets

I nuovi workspace includono hook pre-commit di git-secrets che scansionano i file in staging alla ricerca di pattern di credenziali AWS prima di ogni commit. Questo previene il commit accidentale di access key, secret key e altri valori sensibili.

Sopprimere i Falsi Positivi

I pattern in git-secrets utilizzano espressioni regolari compatibili con egrep. Se git-secrets blocca un commit che non contiene credenziali reali:

# 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'

Puoi anche creare un file .gitallowed alla radice del repository con un’espressione regolare compatibile con egrep per riga (condivisa con il tuo team tramite controllo di versione):

.gitallowed

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

Per i dettagli completi sulla gestione dei pattern, consulta la documentazione di git-secrets.

Configurazione di Nx Plugin for AWS

Il workspace viene fornito con un file aws-nx-plugin.config.mts alla radice. I generatori leggono questo file per scegliere impostazioni predefinite sensate in modo da non dover passare gli stessi flag ogni volta. Due impostazioni sono particolarmente utili:

// 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 — il provider di infrastructure-as-code predefinito (cdk o terraform) utilizzato dai generatori che emettono infrastruttura (ad es. ts#infra, ts#api, py#api). I generatori che accettano un flag --iac hanno come valore predefinito inherit, che legge questo valore.
• containers.engine — la CLI del container (docker o finch) integrata nei comandi generati di build/push/login. Anche le build di image-asset CDK lo rilevano tramite la variabile d’ambiente CDK_DOCKER. Consulta la guida al bundling Docker per i dettagli.

Puoi modificare entrambe le impostazioni in qualsiasi momento — le successive esecuzioni del generatore rileveranno il nuovo valore.