Configurer un monorepo

Tâche 1 : Créer un monorepo

Pour créer un nouveau monorepo, depuis le répertoire de votre choix, exécutez la commande suivante :

pnpm

pnpm create @aws/nx-workspace dungeon-adventure --iac=cdk

yarn

yarn create @aws/nx-workspace dungeon-adventure --iac=cdk

npm

npm create @aws/nx-workspace -- dungeon-adventure --iac=cdk

bun

bun create @aws/nx-workspace dungeon-adventure --iac=cdk

CDK comme fournisseur IaC

Nous utilisons --iac=cdk car nous utiliserons CDK pour l’infrastructure en tant que code dans ce tutoriel. Le Nx Plugin for AWS prend également en charge terraform.

Cela configurera un monorepo NX dans le répertoire dungeon-adventure. Lorsque vous ouvrez le répertoire dans VSCode, vous verrez cette structure de fichiers :

• Répertoire.nx/

  • …
• Répertoire.vscode/

  • …
• Répertoirenode_modules/

  • …
• Répertoirepackages/ c’est ici que résideront vos sous-projets

  • …
• .gitignore
• biome.json configure Biome pour le linting et le formatage
• nx.json configure le CLI Nx et les paramètres par défaut du monorepo
• package.json toutes les dépendances node sont définies ici
• pnpm-lock.yaml ou bun.lock, yarn.lock, package-lock.json selon le gestionnaire de paquets
• pnpm-workspace.yaml si vous utilisez pnpm
• README.md
• tsconfig.base.json tous les sous-projets node étendent ce fichier
• tsconfig.json
• aws-nx-plugin.config.mts configuration du Nx Plugin for AWS

Committez souvent

Il est recommandé de s’assurer que tous vos fichiers non stagés sont commités dans Git avant d’exécuter des générateurs. Cela vous permet de voir ce qui a changé après l’exécution de votre générateur via git diff.

Tâche 2 : Créer l’échafaudage du jeu d’aventure dans le donjon

Une fois l’espace de travail en place, nous créons l’échafaudage des sous-projets du jeu — l’API de jeu, l’agent Story, le serveur MCP d’inventaire, la base de données du jeu et le site web — ainsi que les connexions qui les relient. Il y a deux façons de procéder :

• Rapide — copiez les commandes directement depuis le diagramme ci-dessous et exécutez-les. C’est le moyen le plus rapide d’atteindre le même point de départ.
• Étape par étape — développez la section ci-dessous pour exécuter chaque générateur vous-même et examiner exactement ce que chacun produit.

Le diagramme ci-dessous est l’espace de travail Dungeon Adventure : chaque projet, composant et connexion que vous allez construire dans ce module. Cliquez sur Copier les commandes pour prendre toute la série, puis exécutez-les depuis le répertoire dungeon-adventure que vous avez créé à la Tâche 1.

Loading the diagram…

Étape par étape : exécutez chaque générateur vous-même et voyez ce qu'il produit

Tâche 3 : Mettre à jour notre infrastructure

Mettons à jour packages/infra/src/stacks/application-stack.ts pour instancier certains de nos constructs générés :

+

import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  StoryAgent,
  UserIdentity,
} from '@dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } 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 userIdentity = new UserIdentity(this, 'UserIdentity');

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
    });

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      identity: userIdentity,
    });

    new CfnOutput(this, 'StoryAgentArn', {
      value: storyAgent.agentCoreRuntime.agentRuntimeArn,
    });
    new CfnOutput(this, 'InventoryMcpArn', {
      value: mcpServer.agentCoreRuntime.agentRuntimeArn,
    });

    // Grant the agent permissions to invoke our mcp server
    mcpServer.grantInvokeAccess(storyAgent);

    // Grant the authenticated role access to invoke the api
    gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);

    new GameUI(this, 'GameUI');
  }
}

+-

import { Stack, StackProps } from 'aws-cdk-lib';
import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  StoryAgent,
  UserIdentity,
} from '@dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Construct } from 'constructs';

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

    // The code that defines your stack goes here
    const userIdentity = new UserIdentity(this, 'UserIdentity');

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
    });

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      identity: userIdentity,
    });

    new CfnOutput(this, 'StoryAgentArn', {
      value: storyAgent.agentCoreRuntime.agentRuntimeArn,
    });
    new CfnOutput(this, 'InventoryMcpArn', {
      value: mcpServer.agentCoreRuntime.agentRuntimeArn,
    });

    // Grant the agent permissions to invoke our mcp server
    mcpServer.grantInvokeAccess(storyAgent);

    // Grant the authenticated role access to invoke the api
    gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);

    new GameUI(this, 'GameUI');
  }
}

Intégrations par défaut

Nous fournissons des intégrations par défaut pour notre API de jeu. Par défaut, chaque opération de notre API est mappée à une fonction Lambda individuelle pour gérer cette opération.

Tâche 4 : Construire le code

Il est maintenant temps de construire notre code pour la première fois

En utilisant la ligne de commande, exécutez d’abord la commande suivante pour corriger les problèmes de lint :

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ensuite, exécutez la commande suivante pour un build complet :

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Vous serez invité avec ce qui suit :

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date? …
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Ce message indique que NX a détecté certains fichiers qui peuvent être mis à jour automatiquement pour vous. Dans ce cas, il fait référence aux fichiers tsconfig.json qui n’ont pas de références TypeScript configurées sur les projets référencés.

Sélectionnez l’option Yes, sync the changes and run the tasks pour continuer. Vous devriez remarquer que toutes les erreurs d’import liées à votre IDE sont automatiquement résolues car le générateur de synchronisation ajoutera automatiquement les références TypeScript manquantes !

Tous les artefacts construits sont maintenant disponibles dans le dossier dist/ situé à la racine du monorepo. Il s’agit d’une pratique standard lors de l’utilisation de projets générés par le @aws/nx-plugin car cela ne pollue pas votre arborescence de fichiers avec des fichiers générés. Si vous souhaitez nettoyer vos fichiers, supprimez le dossier dist/ sans vous soucier des artefacts de build dispersés dans l’arborescence de fichiers.

Félicitations ! Vous avez créé tous les sous-projets nécessaires pour commencer à implémenter le cœur de notre jeu d’aventure IA dans le donjon. 🎉🎉🎉