Guide de Démarrage Rapide

Ce guide vous explique les bases de l’installation et de l’utilisation de @aws/nx-plugin pour développer rapidement des projets sur AWS.

Pour un tutoriel plus approfondi sur la création d’une application full-stack, consultez le Tutoriel de l’Aventure du Donjon.

Prérequis

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

Nécessaires

• Git
• Node >= 22 (Nous recommandons d’utiliser un gestionnaire comme NVM pour les versions de Node)
  • vérifiez avec node --version
• PNPM >= 10 (vous pouvez aussi utiliser Yarn >= 4, Bun >= 1 ou NPM >= 10 si vous préférez)
  • vérifiez avec pnpm --version, yarn --version, bun --version ou npm --version
• UV >= 0.5.29
  1. installez Python 3.12 en exécutant : uv python install 3.12.0
  2. vérifiez avec uv python list --only-installed
• Identifiants AWS configurés pour votre compte AWS cible (où votre application sera déployée)

Recommandés

• Docker est requis pour certains générateurs
• Terraform >= 1.12 est requis si vous choisissez de l’utiliser pour l’infrastructure as code au lieu de CDK
  • vérifiez avec terraform --version
• Si vous utilisez VSCode, nous recommandons d’installer l’extension Nx Console pour VSCode

Astuce

Si vous utilisez un assistant IA comme Amazon Q Developer, Cursor, Claude Code ou Cline, vous pouvez également souhaiter installer le plugin Nx pour AWS MCP server.

É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

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --ci=skip

Vous serez invité à choisir votre fournisseur d’infrastructure as code (IaC), soit CDK soit Terraform. Vous pouvez ignorer cette étape en ajoutant --iacProvider à la commande, par exemple :

CDK

pnpm

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

Terraform

pnpm

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

Une fois terminé, accédez au répertoire du projet :

cd my-project

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

Dans ce guide rapide, nous ajouterons une API tRPC, un site React, une authentification Cognito et une infrastructure CDK ou Terraform. Selon votre type de projet, vous pouvez choisir n’importe quelle combinaison de générateurs pour démarrer rapidement. Consultez les Guides dans la barre de navigation à gauche pour voir toutes les options disponibles.

Ajouter une API tRPC

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#trpc-api
5. Remplissez les paramètres requis
   • name: demo-api
   • auth: IAM
6. Cliquez sur Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

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

Ajouter un site React

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#react-website
5. Remplissez les paramètres requis
   • name: demo-website
6. Cliquez sur Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Ajouter l’authentification Cognito

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#react-website#auth
5. Remplissez les paramètres requis
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Cliquez sur Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Connecter le frontend au backend

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 - api-connection
5. Remplissez les paramètres requis
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Cliquez sur Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Ceci configure les fournisseurs nécessaires pour permettre à votre site d’appeler votre API tRPC.

Ajouter l’infrastructure

Ajoutez le projet d’infrastructure selon votre fournisseur IaC choisi.

CDK

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Terraform

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

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

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

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

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

Les modifications apportées à votre site et à votre API seront reflétées en temps réel grâce au rechargement automatique des serveurs.

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

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.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 code CDK nécessaire 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"
}

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

# 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 code Terraform nécessaire pour déployer notre application full-stack.

Construire et déployer l’infrastructure

Exécutez ensuite la commande suivante pour construire votre projet :

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Si vous rencontrez des erreurs de linting, vous pouvez exécuter cette commande pour les corriger automatiquement :

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

Initialisez votre infrastructure :

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Le bootstrapping CDK est requis à la fois pour votre région AWS cible et pour us-east-1 afin de permettre le déploiement du WebACL AWS WAF pour le site.

Terraform

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Le bootstrapping Terraform crée un bucket S3 pour stocker vos fichiers d’état Terraform. Cette opération ne doit être effectuée qu’une fois par combinaison compte AWS/région.

Déployez votre projet :

CDK

pnpm

pnpm nx run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

Cette commande exécutera d’abord terraform plan pour afficher les modifications prévues, puis appliquera ces changements pour déployer votre infrastructure.

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

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

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. Démarrez le serveur local du site

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

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

---

Félicitations ! 🎉 Vous avez déployé avec succès une application full-stack en utilisant @aws/nx-plugin !