Guide de démarrage rapide

Ce guide vous présente les bases de l’installation et de l’utilisation de @aws/nx-plugin pour créer rapidement des projets sur AWS.

Prérequis

Les dépendances globales suivantes sont nécessaires avant de continuer :

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
  2. vérifiez avec uv python list --only-installed

Recommandé

• PNPM >= 11 (vous pouvez également utiliser Yarn >= 4, Bun >= 1, ou NPM >= 11 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.

Étape 1 : Créer un espace de travail

Créez un espace de travail Nx avec le gestionnaire de paquets de votre choix, et ouvrez le répertoire qu’il crée :

Créez votre espace de travail@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

Composez votre commande3

workspaceRequis

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Vous êtes invité à choisir votre fournisseur d’infrastructure en tant que code, soit CDK soit Terraform.

Étape 2 : Construire votre application

Nous allons construire une application full-stack : une API tRPC, un site web React, une authentification Cognito et une infrastructure CDK ou Terraform. Demandez à un assistant IA de la structurer pour vous, ou exécutez les générateurs vous-même — les deux approches aboutissent au même espace de travail.

Avec l’IA

1. Ouvrez l’espace de travail dans votre assistant de codage IA.

   Les nouveaux espaces de travail sont livrés avec le serveur MCP du plugin déjà configuré pour Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot et OpenAI Codex, afin que votre assistant puisse rechercher les générateurs du plugin et les exécuter sans aucune configuration.

2. Demandez l’application :

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   Votre assistant découvre les générateurs via le serveur MCP et les exécute, dans l’ordre requis par leurs dépendances. Examinez les modifications qu’il apporte, puis continuez à l’étape 3.

Avec la CLI

Exécutez les générateurs qui structurent l’application. Utilisez le bouton ci-dessous pour les copier tous, ou exécutez chacun vous-même comme décrit sous le diagramme.

CDK

Loading the diagram…

Terraform

Loading the diagram…

Selon le type de projet que vous construisez, vous pouvez choisir n’importe quelle combinaison de générateurs pour démarrer rapidement votre projet. Consultez les Générateurs dans la barre de navigation à gauche pour voir la liste complète des options, ou essayez le constructeur de graphe pour construire votre espace de travail visuellement.

Ajouter une API tRPC

Exécuter ce générateur@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#api
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape2

nameRequis

framework

trpc

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela créera l’API dans le dossier packages/demo-api.

Ajouter un site web React

Exécuter ce générateur@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#website
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape1

nameRequis

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela génère un nouveau site web React dans packages/demo-website.

Ajouter l’authentification Cognito

Exécuter ce générateur@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#website#auth
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape1

projectRequis

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela configure l’infrastructure nécessaire et le code React pour ajouter l’authentification Cognito à votre site web.

Connecter le frontend au backend

Exécuter ce générateur@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - connection
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape2

sourceProjectRequis

targetProjectRequis

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela configure les fournisseurs nécessaires pour garantir que votre site web peut appeler votre API tRPC.

Ajouter l’infrastructure

Ajoutez le projet d’infrastructure en fonction de votre fournisseur IAC choisi.

CDK

Exécuter ce générateur@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#infra
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape1

nameRequis

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela configure une application CDK que vous pouvez utiliser pour déployer votre infrastructure sur AWS.

Terraform

Exécuter ce générateur@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - terraform#project
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options de cette étape1

nameRequis

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Cela configure un projet Terraform que vous pouvez utiliser pour déployer votre infrastructure sur AWS.

Étape 3 : Exécuter votre site web et votre API localement

Utilisez la commande suivante pour démarrer les serveurs de développement locaux pour votre site web et ses API connectées :

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Votre site web sera disponible à l’adresse http://localhost:4200.

Les modifications apportées à votre site web et à votre API seront reflétées en temps réel, car les serveurs locaux du site web et de l’API se rechargeront automatiquement.

Essayez : appelez l'API depuis votre site web

Étape 4 : Définir les ressources cloud et déployer sur AWS

CDK

Ouvrez packages/infra/src/stacks/application-stack.ts et ajoutez le code suivant :

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

C’est tout le CDK dont nous avons besoin pour déployer notre application full-stack.

Terraform

Ouvrez packages/infra/src/main.tf et ajoutez le code suivant :

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Deploy website
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

C’est tout le Terraform dont nous avons besoin pour déployer notre application full-stack.

Construire et déployer l’infrastructure

Ensuite, exécutez la commande suivante pour construire votre projet :

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Corriger les erreurs de lint et de formatage

Si vous rencontrez des erreurs de lint ou de formatage, vous pouvez exécuter la commande suivante pour les corriger automatiquement.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

L’espace de travail n’est pas synchronisé

Si la construction signale The workspace is out of sync, acceptez l’invite pour synchroniser l’espace de travail ou exécutez directement la commande de synchronisation suivante avant de réessayer la construction :

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Cela écrit les références de projet TypeScript et les entrées de dépendances package.json requises par vos imports.

Initialisez votre infrastructure :

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Régions de bootstrap

Le bootstrap CDK est requis à la fois pour votre région AWS de déploiement cible et pour us-east-1 afin de permettre le déploiement du WebACL AWS WAF pour le site web. Si vous déployez ailleurs, initialisez également us-east-1 :

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Configuration unique

Le bootstrap Terraform crée un bucket S3 pour stocker vos fichiers d’état Terraform. Cela ne doit être fait qu’une seule fois par combinaison compte AWS/région.

Déployez votre projet :

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Planifier avant d’appliquer

Cette commande exécutera d’abord terraform plan pour vous montrer quels changements seront effectués, puis appliquera ces changements pour déployer votre infrastructure.

Étape 5 : Tester le site web avec les ressources cloud déployées

1. Récupérez le fichier runtime-config.json :

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. Démarrez le serveur de site web local

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

Votre site web sera disponible à l’adresse http://localhost:4200 et pointera vers les ressources que vous avez déployées pour l’API et l’authentification.

Pour vous connecter, vous devrez créer un utilisateur dans le pool d’utilisateurs Cognito.

Cliquez ici pour les instructions utilisant l'AWS CLI

Votre site web est également servi depuis CloudFront. Ouvrez le nom de domaine de sa distribution (qui est affiché dans votre terminal après le déploiement) pour utiliser la version fonctionnant entièrement sur AWS.

Félicitations ! 🎉 Vous avez réussi à construire et déployer une application full-stack en utilisant @aws/nx-plugin !

Étape 6 : Nettoyer

Lorsque vous avez terminé, supprimez les ressources que vous avez déployées pour éviter les coûts continus :

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

Ressources conservées

Le pool d’utilisateurs Cognito est créé avec la protection contre la suppression activée, il n’est donc pas supprimé automatiquement. Supprimez-le (ainsi que le rôle IAM que Cognito utilise pour envoyer des messages SMS) manuellement si vous n’en avez plus besoin.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Ressources conservées

Le pool d’utilisateurs Cognito est créé avec la protection contre la suppression activée, il n’est donc pas supprimé automatiquement (la commande destroy signalera un échec). Supprimez-le (ainsi que le rôle IAM que Cognito utilise pour envoyer des messages SMS) manuellement si vous n’en avez plus besoin.

Pour supprimer les ressources de bootstrap, suivez les instructions ci-dessous :

CDK

Supprimez la stack de bootstrap dans chaque région que vous avez initialisée, y compris us-east-1. Cela supprime les rôles de bootstrap et le référentiel d’images de conteneur :

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

Bucket d’assets

Le bucket d’assets est conservé intentionnellement, donc supprimez-le séparément.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Votre état Terraform est également supprimé

Cela vide et supprime le bucket S3 contenant votre état Terraform, donc exécutez-le uniquement une fois que vous avez démantelé toute l’infrastructure déployée.

---

Prochaines étapes

• Dungeon Adventure Tutorial — construisez un jeu d’aventure de donjon IA full-stack, pour une présentation plus approfondie que ce guide.
• Workspaces — comment votre espace de travail est organisé, et la configuration que les générateurs partagent.
• Add to an Existing Project — adoptez le plugin dans votre base de code existante.