Configurare un monorepo

Task 1: Creare un monorepo

Per creare un nuovo monorepo, dalla directory desiderata, esegui il seguente 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 come provider IaC

Utilizziamo --iac=cdk poiché useremo CDK per l’infrastruttura come codice in questo tutorial. Nx Plugin for AWS supporta anche terraform.

Questo configurerà un monorepo NX all’interno della directory dungeon-adventure. Quando apri la directory in VSCode, vedrai questa struttura di file:

• Directory.nx/

  • …
• Directory.vscode/

  • …
• Directorynode_modules/

  • …
• Directorypackages/ qui risiedono i tuoi sotto-progetti

  • …
• .gitignore
• biome.json configura Biome per linting e formattazione
• nx.json configura la CLI Nx e le impostazioni predefinite del monorepo
• package.json tutte le dipendenze node sono definite qui
• pnpm-lock.yaml o bun.lock, yarn.lock, package-lock.json a seconda del package manager
• pnpm-workspace.yaml se si utilizza pnpm
• README.md
• tsconfig.base.json tutti i sotto-progetti basati su node estendono questo
• tsconfig.json
• aws-nx-plugin.config.mts configurazione per Nx Plugin for AWS

Commit frequenti

È buona pratica assicurarsi che tutti i file non staged siano committati in Git prima di eseguire qualsiasi generatore. Questo ti permette di vedere cosa è cambiato dopo aver eseguito il generatore tramite git diff.

Task 2: Scaffolding del Dungeon Adventure Game

Con il workspace in posizione, creiamo lo scaffold dei sotto-progetti del gioco — la Game API, lo Story Agent, il server MCP Inventory, il database del gioco e il sito web — insieme alle connessioni che li collegano. Ci sono due modi per farlo:

• Veloce — copia i comandi direttamente dal diagramma qui sotto ed eseguili. Il modo più veloce per raggiungere lo stesso punto di partenza.
• Passo dopo passo — espandi la sezione qui sotto per eseguire ogni generatore tu stesso ed esaminare esattamente cosa produce ciascuno.

Il diagramma qui sotto è il workspace Dungeon Adventure: ogni progetto, componente e connessione che costruirai in questo modulo. Premi Copy commands per prendere l’intera serie, quindi eseguili dalla directory dungeon-adventure che hai creato nel Task 1.

Loading the diagram…

Passo dopo passo: esegui ogni generatore tu stesso e vedi cosa produce

Task 3: Aggiornare la nostra infrastruttura

Aggiorniamo packages/infra/src/stacks/application-stack.ts per istanziare alcuni dei nostri costrutti generati:

+

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

Integrazioni predefinite

Forniamo integrazioni predefinite per la nostra Game API. Per impostazione predefinita, ogni operazione nella nostra API è mappata a una singola funzione Lambda per gestire quell’operazione.

Task 4: Costruire il codice

Ora è il momento di costruire il nostro codice per la prima volta

Usando la riga di comando, esegui il seguente comando per correggere prima eventuali problemi di lint:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Quindi, esegui il seguente comando per una build completa:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Ti verrà richiesto quanto segue:

 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

Questo messaggio indica che NX ha rilevato alcuni file che possono essere aggiornati automaticamente per te. In questo caso, si riferisce ai file tsconfig.json che non hanno riferimenti TypeScript configurati sui progetti di riferimento.

Seleziona l’opzione Yes, sync the changes and run the tasks per procedere. Dovresti notare che tutti gli errori di import relativi all’IDE vengono risolti automaticamente poiché il generatore di sincronizzazione aggiungerà automaticamente i riferimenti TypeScript mancanti!

Tutti gli artefatti costruiti sono ora disponibili all’interno della cartella dist/ situata alla radice del monorepo. Questa è una pratica standard quando si utilizzano progetti generati da @aws/nx-plugin poiché non inquina il tuo albero dei file con file generati. Nel caso in cui tu voglia pulire i tuoi file, elimina la cartella dist/ senza preoccuparti che gli artefatti di build siano sparsi in tutto l’albero dei file.

Congratulazioni! Hai creato tutti i sotto-progetti richiesti per iniziare a implementare il nucleo del nostro gioco AI Dungeon Adventure. 🎉🎉🎉