Configurar um monorepo

Tarefa 1: Criar um monorepo

Para criar um novo monorepo, dentro do diretório desejado, execute o seguinte 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 Provedor de IaC

Usamos --iac=cdk pois utilizaremos CDK para infraestrutura como código neste tutorial. O Nx Plugin for AWS também suporta terraform.

Isso configurará um monorepo NX dentro do diretório dungeon-adventure. Quando você abrir o diretório no VSCode, verá esta estrutura de arquivos:

• Directory.nx/

  • …
• Directory.vscode/

  • …
• Directorynode_modules/

  • …
• Directorypackages/ aqui é onde seus sub-projetos residirão

  • …
• .gitignore
• biome.json configura o Biome para linting e formatação
• nx.json configura o CLI do Nx e os padrões do monorepo
• package.json todas as dependências node são definidas aqui
• pnpm-lock.yaml ou bun.lock, yarn.lock, package-lock.json dependendo do gerenciador de pacotes
• pnpm-workspace.yaml se estiver usando pnpm
• README.md
• tsconfig.base.json todos os sub-projetos baseados em node estendem este
• tsconfig.json
• aws-nx-plugin.config.mts configuração para o Nx Plugin for AWS

Faça Commits Frequentes

É uma boa prática garantir que todos os seus arquivos não preparados estejam commitados no Git antes de executar qualquer gerador. Isso permite que você veja o que mudou após executar seu gerador via git diff.

Tarefa 2: Estruturar o Jogo de Aventura em Masmorra

Com o workspace configurado, estruturamos os sub-projetos do jogo — a API do Jogo, Agente de História, servidor MCP de Inventário, banco de dados do jogo e website — juntamente com as conexões que os conectam. Existem duas maneiras de fazer isso:

• Rápido — copie os comandos diretamente do diagrama abaixo e execute-os. A maneira mais rápida de chegar ao mesmo ponto de partida.
• Passo a Passo — expanda a seção abaixo para executar cada gerador você mesmo e examinar exatamente o que cada um produz.

O diagrama abaixo é o workspace Dungeon Adventure: cada projeto, componente e conexão que você construirá neste módulo. Clique em Copy commands para pegar toda a série, depois execute-os de dentro do diretório dungeon-adventure que você criou na Tarefa 1.

Loading the diagram…

Passo a Passo: execute cada gerador você mesmo e veja o que ele produz

Tarefa 3: Atualizar nossa infraestrutura

Vamos atualizar packages/infra/src/stacks/application-stack.ts para instanciar alguns dos nossos constructs gerados:

+

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

Integrações Padrão

Fornecemos integrações padrão para nossa Game API. Por padrão, cada operação em nossa API é mapeada para uma função Lambda individual para lidar com essa operação.

Tarefa 4: Construir o código

Agora é hora de construirmos nosso código pela primeira vez

Usando a linha de comando, execute o seguinte comando para corrigir quaisquer problemas de lint primeiro:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Em seguida, execute o seguinte comando para um build completo:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Você será solicitado com o seguinte:

 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

Esta mensagem indica que o NX detectou alguns arquivos que podem ser atualizados automaticamente para você. Neste caso, está se referindo aos arquivos tsconfig.json que não têm referências Typescript configuradas em projetos referenciados.

Selecione a opção Yes, sync the changes and run the tasks para prosseguir. Você deve notar que todos os seus erros de importação relacionados ao IDE são resolvidos automaticamente, pois o gerador de sincronização adicionará as referências typescript ausentes automaticamente!

Todos os artefatos construídos agora estão disponíveis dentro da pasta dist/ localizada na raiz do monorepo. Esta é uma prática padrão ao usar projetos gerados pelo @aws/nx-plugin, pois não polui sua árvore de arquivos com arquivos gerados. No caso de você querer limpar seus arquivos, exclua a pasta dist/ sem se preocupar com artefatos de build espalhados por toda a árvore de arquivos.

Parabéns! Você criou todos os sub-projetos necessários para começar a implementar o núcleo do nosso jogo de Aventura em Masmorra com IA. 🎉🎉🎉