Configurar un monorepo

Tarea 1: Crear un monorepo

Para crear un nuevo monorepo, desde el directorio deseado, ejecuta el siguiente comando:

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 como proveedor de IaC

Usamos --iac=cdk ya que utilizaremos CDK para infraestructura como código en este tutorial. El Nx Plugin for AWS también soporta terraform.

Esto configurará un monorepo NX dentro del directorio dungeon-adventure. Cuando abras el directorio en VSCode, verás esta estructura de archivos:

• Directorio.nx/

  • …
• Directorio.vscode/

  • …
• Directorionode_modules/

  • …
• Directoriopackages/ aquí es donde residirán tus sub-proyectos

  • …
• .gitignore
• biome.json configura Biome para linting y formateo
• nx.json configura el CLI de Nx y los valores predeterminados del monorepo
• package.json todas las dependencias de node se definen aquí
• pnpm-lock.yaml o bun.lock, yarn.lock, package-lock.json dependiendo del gestor de paquetes
• pnpm-workspace.yaml si usas pnpm
• README.md
• tsconfig.base.json todos los sub-proyectos basados en node extienden esto
• tsconfig.json
• aws-nx-plugin.config.mts configuración para el Nx Plugin for AWS

Haz commits frecuentes

Es una buena práctica asegurarse de que todos tus archivos sin preparar estén confirmados en Git antes de ejecutar cualquier generador. Esto te permite ver qué ha cambiado después de ejecutar tu generador mediante git diff.

Tarea 2: Estructurar el Dungeon Adventure Game

Con el espacio de trabajo listo, estructuramos los sub-proyectos del juego: la Game API, el Story Agent, el servidor MCP de inventario, la base de datos del juego y el sitio web, junto con las conexiones que los unen. Hay dos formas de hacerlo:

• Rápido — copia los comandos directamente del diagrama a continuación y ejecútalos. La forma más rápida de llegar al mismo punto de partida.
• Paso a paso — expande la sección a continuación para ejecutar cada generador tú mismo y examinar exactamente lo que produce cada uno.

El diagrama a continuación es el espacio de trabajo de Dungeon Adventure: cada proyecto, componente y conexión que construirás en este módulo. Haz clic en Copy commands para tomar toda la serie y luego ejecútalos desde dentro del directorio dungeon-adventure que creaste en la Tarea 1.

Loading the diagram…

Paso a paso: ejecuta cada generador tú mismo y observa lo que produce

Tarea 3: Actualizar nuestra infraestructura

Actualicemos packages/infra/src/stacks/application-stack.ts para instanciar algunos de nuestros constructs generados:

+

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');
  }
}

Integraciones predeterminadas

Proporcionamos integraciones predeterminadas para nuestra Game API. Por defecto, cada operación en nuestra API se mapea a una función Lambda individual para manejar esa operación.

Tarea 4: Compilar el código

Ahora es el momento de compilar nuestro código por primera vez

Usando la línea de comandos, ejecuta el siguiente comando para corregir primero cualquier problema de lint:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Luego, ejecuta el siguiente comando para una compilación completa:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Se te presentará lo siguiente:

 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

Este mensaje indica que NX ha detectado algunos archivos que pueden actualizarse automáticamente. En este caso, se refiere a los archivos tsconfig.json que no tienen referencias de TypeScript configuradas en los proyectos referenciados.

Selecciona la opción Yes, sync the changes and run the tasks para continuar. ¡Deberías notar que todos los errores de importación relacionados con tu IDE se resuelven automáticamente, ya que el generador de sincronización agregará las referencias de TypeScript faltantes automáticamente!

Todos los artefactos compilados ahora están disponibles dentro de la carpeta dist/ ubicada en la raíz del monorepo. Esta es una práctica estándar cuando se usan proyectos generados por el @aws/nx-plugin, ya que no contamina tu árbol de archivos con archivos generados. En caso de que quieras limpiar tus archivos, elimina la carpeta dist/ sin preocuparte por los artefactos de compilación dispersos por todo el árbol de archivos.

¡Felicitaciones! Has creado todos los sub-proyectos necesarios para comenzar a implementar el núcleo de nuestro juego de aventuras AI en mazmorras. 🎉🎉🎉