Skip to content
@aws/nx-plugin
Blog

Set up a monorepo

Task 1: Create a monorepo

Section titled “Task 1: Create a monorepo”

To create a new monorepo, from within your desired directory, run the following command:

Terminal window
npx create-nx-workspace@21.6.8 dungeon-adventure --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

This will set up a NX monorepo within the dungeon-adventure directory. When you open the directory in VSCode, you will see this file structure:

  • Directory.nx/
    • …
  • Directory.vscode/
    • …
  • Directorynode_modules/
    • …
  • Directorypackages/ this is where your sub-projects will reside
    • …
  • .gitignore
  • .npmrc
  • .prettierignore
  • .prettierrc
  • nx.json configures the Nx CLI and monorepo defaults
  • package.json all node dependencies are defined here
  • pnpm-lock.yaml or bun.lock, yarn.lock, package-lock.json depending on package manager
  • pnpm-workspace.yaml if using pnpm
  • README.md
  • tsconfig.base.json all node based sub-projects extend this
  • tsconfig.json
  • aws-nx-plugin.config.mts configuraton for the Nx Plugin for AWS

We can now start creating our different sub-projects using the @aws/nx-plugin.

Task 2: Create a Game API

Section titled “Task 2: Create a Game API”

First, let’s create our Game API. To do this, create a tRPC API called GameApi using these steps:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#trpc-api
  5. Fill in the required parameters
    • name: GameApi
  6. Click Generate

You will see some new files appear in your file tree.

Click here to examine these files in more detail.

Task 3: Create Story agents

Section titled “Task 3: Create Story agents”

Now let’s create our Story Agents.

Story agent: Python project

Section titled “Story agent: Python project”

To create a Python project:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - py#project
  5. Fill in the required parameters
    • name: story
  6. Click Generate

You will see some new files appear in your file tree.

Click here to examine these files in more detail.

Story agent: Strands Agent

Section titled “Story agent: Strands Agent”

To add a Strands agent to the project with the py#strands-agent generator:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - py#strands-agent
  5. Fill in the required parameters
    • project: story
  6. Click Generate

You will see some new files appear in your file tree.

Click here to examine these files in more detail.

Task 4: Set up inventory tools

Section titled “Task 4: Set up inventory tools”

Inventory: TypeScript project

Section titled “Inventory: TypeScript project”

Let us create an MCP server to provide tools for our Story Agent to manage a player’s inventory.

First, we create a TypeScript project:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#project
  5. Fill in the required parameters
    • name: inventory
  6. Click Generate

This will create an empty TypeScript project.

Click here to examine these files in more detail.

Inventory: MCP server

Section titled “Inventory: MCP server”

Next, we’ll add an MCP server to our TypeScript project:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#mcp-server
  5. Fill in the required parameters
    • project: inventory
  6. Click Generate

This will add an MCP server.

Click here to examine these files in more detail.

Task 5: Create the User Interface (UI)

Section titled “Task 5: Create the User Interface (UI)”

In this task, we will create the UI which will allow you to interact with the game.

Game UI: Website

Section titled “Game UI: Website”

To create the UI, create a website called GameUI using these steps:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#react-website
  5. Fill in the required parameters
    • name: GameUI
  6. Click Generate

You will see some new files appear in your file tree.

Click here to examine these files in more detail.

Game UI: Auth

Section titled “Game UI: Auth”

Let us configure our Game UI to require authenticated access via Amazon Cognito using these steps:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#react-website#auth
  5. Fill in the required parameters
    • cognitoDomain: game-ui
    • project: @dungeon-adventure/game-ui
    • allowSignup: true
  6. Click Generate

You will see some new files appear/change in your file tree.

Click here to examine these files in more detail.

Game UI: Connect to Game API

Section titled “Game UI: Connect to Game API”

Let us configure our Game UI to connect to our previously created Game API.

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - api-connection
  5. Fill in the required parameters
    • sourceProject: @dungeon-adventure/game-ui
    • targetProject: @dungeon-adventure/game-api
  6. Click Generate

You will see some new files have appear/change in your file tree.

Click here to examine these files in more detail.

Game UI: Infrastructure

Section titled “Game UI: Infrastructure”

Let us create the final sub-project for the CDK infrastructure.

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#infra
  5. Fill in the required parameters
    • name: infra
  6. Click Generate

You will see some new files have appear/change in your file tree.

Click here to examine these files in more detail.

Task 6: Update our infrastructure

Section titled “Task 6: Update our infrastructure”

Let’s update packages/infra/src/stacks/application-stack.ts to instantiate some of our generated constructs:

import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  RuntimeConfig,
  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 { userPool, userPoolClient } = userIdentity;


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


    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedAudience: [userPoolClient.userPoolClientId],
        },
      },
      environment: {
        INVENTORY_MCP_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });
    // Add the Story Agent ARN to runtime-config.json so it can be referenced by the website
    RuntimeConfig.ensure(this).config.agentArn =
      storyAgent.agentCoreRuntime.arn;


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


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


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


    // Ensure this is instantiated last so our runtime-config.json can be automatically configured
    new GameUI(this, 'GameUI');
  }
}

Task 7: Build the code

Section titled “Task 7: Build the code”
Now it's time for us to build our code for the first time

Using the command line, run:

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

You will be prompted with the following:

Terminal window
 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

This message indicates that NX has detected some files which can be updated automatically for you. In this case, it is referring to the tsconfig.json files which do not have Typescript references set up on references projects.

Select the Yes, sync the changes and run the tasks option to proceed. You should notice all of you IDE related import errors get automatically resolved as the sync generator will add the missing typescript references automatically!

All built artifacts are now available within the dist/ folder located at the root of the monorepo. This is a standard pactice when using projects generated by the @aws/nx-plugin as it does not pollute your file-tree with generated files. In the event you want to clean your files, delete the dist/ folder without worrying about generated files being littered throughout the file tree.

Congratulations! You’ve created all of the required sub-projects required to start implementing the core of our AI Dungeon Adventure game. 🎉🎉🎉