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

Crea il tuo workspace@aws/nx-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

Componi il tuo comando8

workspaceObbligatorio

iac

cdkterraform

containers

inferdockerfinch

gitSecrets

true

mcp

true

module

esmcjs

catalog

true

preferInstallDependencies

true

Opzioni

Opzioni del generatore7 opzioni

iacenumPredefinito: cdk

Il provider IaC preferito.

cdkterraform

containersenumPredefinito: 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).

inferdockerfinch

gitSecretsbooleanPredefinito: true

Se configurare git-secrets per impedire il commit di credenziali AWS.

mcpbooleanPredefinito: true

Se configurare il Plugin Nx per il server AWS MCP per l'uso da parte di agenti di codifica.

moduleenumPredefinito: esm

Formato del modulo per il codice TypeScript e la configurazione generati.

esmcjs

catalogbooleanPredefinito: 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à.

preferInstallDependenciesbooleanPredefinito: 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
• biome.json Biome configuration for linting and formatting
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• Directory.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• .gitallowed Patterns git-secrets treats as false positives
• 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. 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.

Parallelismo

I nuovi workspace impostano parallel in nx.json, che controlla quante attività Nx esegue contemporaneamente:

nx.json

{
  "parallel": 8
}

Abbassalo se stai costruendo su una macchina con meno core o memoria limitata. Puoi anche sovrascriverlo per singola invocazione:

pnpm

pnpm nx run-many --target build --parallel=4

yarn

yarn nx run-many --target build --parallel=4

npm

npx nx run-many --target build --parallel=4

bun

bunx nx run-many --target build --parallel=4

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.

Configurazione MCP

Il server MCP del plugin è configurato come server MCP a livello di progetto per Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot e OpenAI Codex, in modo che il tuo assistente di codifica possa scoprire ed eseguire i generatori del plugin senza alcuna configurazione. La configurazione viene committata con il tuo workspace, dando a tutti nel tuo team la stessa configurazione. Rimuovi le configurazioni per gli assistenti di codifica che tu e il tuo team non utilizzate.

Git Secrets

I workspace sono configurati con 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.

Lo script è incluso nel workspace in .git-secrets/git-secrets ed eseguito dall’hook .husky/pre-commit, quindi non c’è nulla da installare — ma non è nel tuo PATH, quindi invocalo tramite percorso piuttosto che come git secrets.

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 (-a is the allowed flag)
bash .git-secrets/git-secrets --add -a -- 'my-regex-pattern'

# Allow a literal string, escaping special characters (-l is the literal flag)
bash .git-secrets/git-secrets --add -a -l -- 'my-literal+string'

# List what is currently allowed
git config --get-all secrets.allowed

Questi vengono registrati nella tua configurazione git locale, quindi si applicano solo al tuo clone. Per condividere una soppressione con il tuo team, aggiungila invece al file .gitallowed alla radice del repository — un’espressione regolare compatibile con egrep per riga, confrontata con <path>:<line-number>:<line-contents>:

.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:

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

export default {
  iac: {
    provider: 'cdk', // or 'terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
  packageManager: {
    catalogs: true, // or false
  },
} 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.
• packageManager.catalogs — se i generatori registrano le versioni delle dipendenze nel catalog del package manager e le referenziano con il protocollo catalog: (vedi Single Version Policy). Impostalo su false per far sì che i generatori scrivano intervalli di versione diretti nel package.json di ogni progetto. Non ha effetto su npm, che non ha un catalog.

Il generatore license aggiunge una chiave license a questo stesso file per configurare il proprio comportamento.

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