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.

Tutoriel Full-Stack

Pour un tutoriel plus approfondi sur la création d’une application full-stack, consultez le Tutoriel Dungeon Adventure.

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

Étape 1 : Initialiser un nouvel espace de travail Nx

Exécutez la commande suivante pour créer un espace de travail Nx avec le gestionnaire de paquets de votre choix :

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

Choisir un fournisseur IaC

Vous serez invité à choisir votre fournisseur d’infrastructure en tant que code (IaC) préféré, soit CDK soit Terraform. Vous pouvez ignorer l’invite en exécutant la commande avec --iac, par exemple :

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

Une fois terminé, naviguez vers le répertoire du projet :

cd my-project

Étape 2 : Utiliser les générateurs pour structurer votre projet

Nous allons ajouter une API tRPC, un site web React, une authentification Cognito et une infrastructure CDK ou Terraform dans ce guide de démarrage rapide. 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.

Comme raccourci, vous pouvez utiliser le bouton ci-dessous pour copier les commandes permettant de structurer l’application complète.

Loading the diagram…

Construire avec l’IA

Le Nx Plugin for AWS MCP Server est déjà configuré dans votre espace de travail, vous pouvez donc demander à votre agent de codage IA préféré comme Kiro ou Claude de construire ces projets pour vous au lieu de taper les commandes CLI vous-même.

Sinon, suivez les étapes ci-dessous pour exécuter chaque générateur vous-même.

Ajouter une API tRPC

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

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
   • name: demo-api
   • framework: trpc
   • auth: iam
6. Cliquez sur Generate

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

Ajouter un site web React

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

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
   • name: demo-website
6. Cliquez sur Generate

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

Ajouter l’authentification Cognito

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

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
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Cliquez sur Generate

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

Connecter le frontend au backend

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

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
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Cliquez sur Generate

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

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
   • name: infra
6. Cliquez sur Generate

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

Terraform

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

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
   • name: infra
6. Cliquez sur Generate

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.

É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 { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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 :

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 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]
}

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

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

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

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.

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.

---

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