Ajouter à un projet existant

Tous les projets ne commencent pas avec pnpm create @aws/nx-workspace. Si vous avez déjà un espace de travail Nx — ou un monorepo auquel vous pouvez ajouter Nx — vous pouvez adopter @aws/nx-plugin de manière incrémentale sans recréer votre projet.

Astuce

Vous pouvez utiliser l’outil de codage agentique de votre choix pour ajouter le plugin à votre place, en utilisant le serveur MCP. Essayez le prompt :

Add the Nx Plugin for AWS to this project.

Prérequis

Requis

• Git
• Node >= 22 (Nous recommandons d’utiliser quelque chose comme NVM pour gérer vos versions de node)
  • vérifiez en exécutant node --version
• UV >= 0.5.29
  1. installez Python 3.14 en exécutant : uv python install 3.14.0
  2. vérifiez avec uv python list --only-installed

Recommandé

• PNPM >= 11 (vous pouvez également utiliser Yarn >= 4, Bun >= 1, ou NPM >= 10 si vous préférez)
  • vérifiez en exécutant pnpm --version, yarn --version, bun --version ou npm --version
• AWS Credentials configurées pour votre compte AWS cible sont requises pour déployer votre application (ainsi que pour certains workflows de développement local).
• Docker ou Finch >= 1.6.0 est requis pour certains générateurs. Pour Docker, les multi-platform builds doivent être configurés ; Finch prend en charge les multi-platform builds nativement.
• Terraform >= 1.12 est requis si vous choisissez de l’utiliser pour l’infrastructure en tant que code au lieu de CDK
  • vérifiez en exécutant terraform --version
• Si vous utilisez VSCode, nous recommandons d’installer le Nx Console VSCode Plugin.

Configuration de l’Assistant IA

Si vous utilisez un Assistant IA tel que Kiro, Kiro CLI, Cursor, Claude Code ou Cline, vous pouvez également souhaiter installer le serveur MCP Nx Plugin for AWS.

Avant de commencer

Enregistrez et commitez d’abord tout travail en cours, afin que les modifications apportées à chaque étape puissent être examinées — et annulées — à tout moment.

Ajouter Nx à un projet non-Nx

Si votre projet n’utilise pas encore Nx, ajoutez-le d’abord avec nx init. C’est une étape que Nx lui-même gère ; le plugin s’appuie sur un espace de travail Nx fonctionnel. Cela fonctionne sur un package simple, un espace de travail npm/pnpm/yarn/bun, un Turborepo ou un monorepo Lerna :

pnpm

pnpm dlx nx@23.1.1 init

yarn

yarn dlx nx@23.1.1 init

npm

npx nx@23.1.1 init

bun

bunx nx@23.1.1 init

Suivez les invites pour ajouter Nx à votre espace de travail. Pour plus de détails, consultez la documentation Nx.

pnpm workspaces

pnpm n’exécute les scripts d’installation que pour les packages autorisés, et nx a besoin de son script d’installation — sans cela, l’installation que nx init effectue peut échouer, laissant un placeholder set this to true or false dans pnpm-workspace.yaml. Autorisez-le avant d’exécuter nx init :

pnpm-workspace.yaml

allowBuilds:
  - nx

Projets non-Node (Python, Go, Java, Rust, …)

Nx et le plugin sont distribués sous forme de packages npm, donc un projet sans outillage Node.js a besoin d’un package.json racine minimal avant que nx init puisse faire quoi que ce soit d’utile :

package.json

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

Créez ce fichier, puis exécutez nx init et ajoutez le plugin comme d’habitude. Votre outillage de langage existant reste intact — les projets Nx générés par le plugin (y compris les projets Python) cohabitent avec votre code existant, et vous pouvez intégrer votre build existant dans Nx de manière incrémentale.

Pour placer vos projets existants sous Nx, vous avez plusieurs options selon le langage :

• Langages avec un plugin Nx officiel — Java (Gradle ou Maven) et .NET ont des plugins dédiés qui infèrent automatiquement les tâches de vos projets. Ajoutez celui qui convient, par exemple nx add @nx/gradle, nx add @nx/maven ou nx add @nx/dotnet.
• Langages avec un plugin communautaire — par exemple Go (@nx-go/nx-go) ou Rust (@monodon/rust). Parcourez le registre de plugins Nx pour d’autres.
• Tout autre langage — ajoutez un project.json à chaque projet et définissez ses targets pour exécuter vos commandes de build existantes, afin que nx build <project> (et nx run-many) les pilotent. Consultez le guide de l’espace de travail pour savoir comment project.json et les targets sont configurés.

Projets à package unique

Le plugin est conçu pour les monorepos — il génère chaque projet dans son propre répertoire sous packages/. Si vous partez d’un projet à package unique (un package.json à la racine avec votre source directement en dessous, sans workspaces), déplacez votre package existant dans packages/ avant d’adopter le plugin afin que votre projet se trouve aux côtés de ceux que le plugin génère :

1. Créez un répertoire packages/<votre-package>/ et déplacez-y votre source, package.json et tsconfig.json.

2. Créez un nouveau package.json racine qui agit comme manifeste de l’espace de travail plutôt que comme un projet lui-même :

   package.json

   {
     "name": "<your-workspace>",
     "private": true,
     "type": "module"
   }

3. Déclarez l’espace de travail pour que votre gestionnaire de packages découvre les projets sous packages/. Pour pnpm, ajoutez un pnpm-workspace.yaml :

   pnpm-workspace.yaml

   packages:
     - packages/*

   Pour npm/yarn/bun, ajoutez plutôt un champ workspaces au package.json racine :

   package.json

   {
     "workspaces": ["packages/*"]
   }

4. Exécutez nx init (si ce n’est pas déjà fait), puis ajoutez le plugin.

Gestionnaire de packages

Les projets du plugin sont générés sous un répertoire packages/. pnpm lit les globs de l’espace de travail depuis pnpm-workspace.yaml ; les autres gestionnaires de packages lisent le champ workspaces du package.json racine — init met à jour celui que votre espace de travail utilise.

Ajouter le plugin

Utilisez nx add, qui installe le plugin à une version compatible avec votre installation Nx, puis exécute son générateur init pour configurer votre espace de travail :

pnpm

pnpm nx add @aws/nx-plugin

yarn

yarn nx add @aws/nx-plugin

npm

npx nx add @aws/nx-plugin

bun

bunx nx add @aws/nx-plugin

Une fois terminé, votre espace de travail est prêt — choisissez les générateurs dont vous avez besoin et commencez à générer des projets.

Ce que ce générateur configure

L’ajout du plugin apporte les modifications déterministes dont un espace de travail a besoin pour exécuter les générateurs du plugin. Il préserve le format de module de votre espace de travail : un espace de travail dont le package.json racine a type: "module" reste en ESM, tout le reste reste en CommonJS, et le code généré suit le mouvement. Il n’écrase pas les fichiers existants, et vous devrez peut-être apporter quelques modifications manuelles après cette étape en fonction de votre configuration existante.

Il crée ou met à jour les fichiers suivants :

• aws-nx-plugin.config.mts enregistre votre fournisseur IaC choisi (CDK ou Terraform) et votre moteur de conteneurs ; les générateurs lisent iac.provider depuis ici
• nx.json enregistre les générateurs de synchronisation (@nx/js:typescript-sync et @aws/nx-plugin:ts#sync) sur la target compile afin que les références de projet TypeScript restent synchronisées
• tsconfig.json une configuration TypeScript racine référençant les projets de votre espace de travail, que la synchronisation TypeScript de Nx maintient à jour
• tsconfig.base.json les options de compilateur partagées que les projets TypeScript du plugin étendent (voir ci-dessous pour ce qu’il contient)
• pnpm-workspace.yaml (pnpm uniquement) autorise les scripts de build dont les dépendances du plugin ont besoin (@swc/core, esbuild, nx, sharp)
• package.json scripts de commodité pour les tâches courantes, plus les devDependencies @aws/nx-plugin, @aws/nx-plugin-mcp, nx, @nx/js, @nx/workspace, typescript et Biome
• biome.json configuration par défaut du formateur et du linter Biome
• .mcp.json configure le serveur MCP pour les agents de codage pris en charge sauf si désactivé (également les équivalents .cursor/, .kiro/, .gemini/, .vscode/ et .codex/). Il exécute le @aws/nx-plugin-mcp propre à l’espace de travail, donc le serveur correspond toujours à la version installée dans votre espace de travail

La configuration du serveur MCP peut être désactivée avec --mcp=false.

Cliquez ici pour voir les options de compilateur qu'un tsconfig.base.json créé contient.

Options

Paramètre	Type	Par défaut	Description
iac	cdk | terraform	cdk	Le fournisseur IaC préféré.
mcp	boolean	true	Indique s'il faut configurer le plugin Nx pour le serveur AWS MCP afin qu'il soit utilisé par les agents de codage.
containers	infer | docker | finch	infer	Le moteur de conteneurs à utiliser pour build/push/login. 'infer' choisit docker s'il est installé, sinon finch (en se repliant sur docker si aucun des deux n'est installé).
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors du traitement par lots de plusieurs générateurs (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Dépannage

nx build <project> ne fonctionne plus pour une bibliothèque TypeScript existante

La première exécution de ts#project configure le plugin @nx/js/typescript pour inférer la target de build TypeScript comme compile (le plugin réserve build pour orchestrer lint, compile et test). Les bibliothèques existantes qui s’appuient sur la target build inférée sont également inférées comme compile — exécutez nx run <project>:compile, ou utilisez nx run-many --target build,compile. Les bibliothèques avec une target build explicite dans leur project.json ne sont pas affectées.

The workspace is out of sync

Les références de projet TypeScript nécessitent une synchronisation. init enregistre les générateurs de synchronisation ; exécutez :

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

ERR_PNPM_IGNORED_BUILDS pendant l’installation

pnpm ignore les scripts d’installation pour les packages qui ne sont pas autorisés. init autorise ceux dont l’outillage du plugin a besoin (@swc/core, esbuild, nx, sharp) dans pnpm-workspace.yaml, mais le blocage peut se produire pendant nx add @aws/nx-plugin lui-même — avant que init ne soit exécuté. Exécutez pnpm approve-builds et approuvez les packages listés (ou ajoutez-les sous allowBuilds:), puis relancez l’installation.

nx sync se bloque, ou plugin worker ... exited before the connection was established

Si deux versions différentes de nx sont présentes dans le même arbre node_modules (exécutez npm ls nx pour confirmer), leur IPC plugin-worker se bloque. Le générateur init épingle la devDependency nx racine à la version que les propres packages @nx/* du plugin résolvent, mais une installation ultérieure d’un autre package @nx/* à une version de patch différente peut réintroduire l’incompatibilité. Alignez chaque entrée nx et @nx/* dans votre package.json racine sur une seule version et réinstallez.

ts.readConfigFile is not a function

Votre espace de travail a TypeScript 7 installé, que Nx ne prend pas encore en charge — les plugins de Nx s’appuient sur l’API de compilateur en processus de TypeScript, que TypeScript 7 ne fournit plus. Épinglez typescript dans votre package.json racine à la version que le plugin utilise (le générateur init installe une version compatible) et réinstallez.

Recursive task invocation detected

Votre package.json racine est enregistré comme un projet Nx (il a une clé "nx", que nx init ajoute pour un repo à package unique) et porte un script build de nx run-many --target build. Nx infère alors une target build sur la racine qui s’appelle elle-même. Déplacez votre source dans packages/<votre-package>/ pour que la racine devienne un manifeste d’espace de travail plutôt qu’un projet — voir Projets à package unique. (Les propres presets standalone de Nx évitent cela en définissant "nx": { "includedScripts": [] } sur le package racine ; vous pouvez faire de même comme alternative plus rapide.)

Erreurs TypeScript dans vos projets existants après l’ajout du plugin (TS6059, TS7016, TS5011, NG4006)

Les propres projets générés du plugin portent les paramètres TypeScript dont ils ont besoin dans leur tsconfig.lib.json par projet, donc ils se construisent indépendamment de votre tsconfig.base.json. Ces erreurs apparaissent plutôt dans un projet préexistant qui hérite d’un tsconfig.base.json créé par init (avec composite/emitDeclarationOnly/nodenext) mais n’est pas compatible avec ces paramètres — par exemple, le compilateur Angular rejette emitDeclarationOnly (NG4006), ou un projet qui définit outDir sans rootDir en a maintenant besoin (TS5011). Ajoutez des surcharges tsconfig par projet redéclarant les options conflictuelles pour ces projets (par exemple "rootDir": "src"), ou pointez les projets du plugin et vos projets vers des configs de base séparées.

init ne réécrit jamais un tsconfig.base.json existant, précisément pour qu’il ne puisse pas casser silencieusement les projets qui en héritent — résoudre ces incompatibilités est une décision que vous seul pouvez prendre pour votre base de code.

ESM et CommonJS

Le format de module est à l’échelle de l’espace de travail, lu depuis le champ type du package.json racine : type: "module" signifie ESM, tout le reste (y compris l’absence de champ type) signifie CommonJS. init préserve celui que votre espace de travail utilise, et les générateurs TypeScript du plugin émettent du code correspondant. Si vous souhaitez changer plus tard, modifiez le type racine — mais c’est une migration de votre code existant, pas quelque chose que init fait pour vous.