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.

Creazione di 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
addTsPlugin	boolean	true	Se aggiungere il plugin ts.
iacProvider	string	CDK	Il provider IaC preferito.
gitSecrets	boolean	true	Se configurare git-secrets per impedire il commit di credenziali AWS.
containerEngine	string	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).

Struttura del Workspace

• Directorypackages/ I tuoi progetti risiedono qui

  • …
• package.json Root package.json per il tuo monorepo
• nx.json Configurazione Nx (target comuni, generatori di sincronizzazione, caching)
• tsconfig.base.json Configurazione TypeScript radice
• aws-nx-plugin.config.mts Configurazione Nx Plugin for AWS
• Directory.git-secrets/ Script bash git-secrets vendorizzato per la scansione delle credenziali

  • …
• Directory.husky/ Hook Git

  • …

Nx

Nx è un sistema di build indipendente dal linguaggio per monorepo, che gestisce le dipendenze tra progetti scritti in qualsiasi linguaggio di programmazione e i task per compilarli. 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 i task di un progetto, noti come target, che definiscono come un progetto viene compilato, 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 compilazione 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 progetti in linguaggi non direttamente supportati dal Nx Plugin for AWS, puoi spesso trovare un generatore nel Nx Plugin Registry per aiutarti. È comunque semplice aggiungere un progetto di qualsiasi linguaggio nel 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 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 sulla cache 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 incorrono in problemi di mancata corrispondenza delle versioni.

Dal punto di vista di Node, questo significa un singolo lockfile alla radice con un singolo node_modules contenente tutte le dipendenze. Se devi aggiungere una nuova dipendenza, aggiungila nel package.json radice.

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

Comandi Comuni

Build

Compila 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

Se hai un sito web, avvialo insieme a tutti i componenti connessi localmente:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Sync

Esegui qualsiasi sync generator, che ad esempio sincronizza i riferimenti di progetto 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 ESLint per l’analisi statica e Prettier per la formattazione del codice. L’esecuzione di lint applica entrambi a tutti i progetti.

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.

Soppressione dei Falsi Positivi

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

# Consenti un pattern regex specifico
git secrets --add --allowed 'my-regex-pattern'

# Consenti una stringa letterale (i caratteri speciali vengono escapati)
git secrets --add --allowed --literal 'my-literal+string'

Puoi anche creare un file .gitallowed nella radice del repository con una regex compatibile con egrep per riga (condiviso con il tuo team tramite controllo di versione):

.gitallowed

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

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

Configurazione Nx Plugin for AWS

Il workspace include un file aws-nx-plugin.config.mts nella 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 infrastructure-as-code predefinito (CDK o Terraform) utilizzato dai generatori che emettono infrastruttura (ad es. ts#infra, ts#trpc-api, py#fast-api). I generatori che accettano un flag --iacProvider hanno come valore predefinito Inherit, che legge questo valore.
• containers.engine — la CLI dei container (docker o finch) integrata nei comandi generati di build/push/login. Anche le build di image-asset CDK utilizzano questo valore 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 dei generatori utilizzeranno il nuovo valore.