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
pnpm create @aws/nx-workspace dungeon-adventure --iac=cdk

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
  • biome.json configures Biome for linting and formatting
  • 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

Task 2: Scaffold the Dungeon Adventure Game

Section titled “Task 2: Scaffold the Dungeon Adventure Game”

With the workspace in place, we scaffold the game’s sub-projects — the Game API, Story Agent, Inventory MCP server, game database, and website — along with the connections that wire them together. There are two ways to do this:

  • Quick — copy the commands straight from the diagram below and run them. The fastest way to reach the same starting point.
  • Step By Step — expand the section below to run each generator yourself and examine exactly what each one produces.

The diagram below is the Dungeon Adventure workspace: every project, component, and connection you’ll build in this module. Hit Copy commands to take the whole series, then run them from within the dungeon-adventure directory you created in Task 1.

Loading the diagram…

Step By Step: run each generator yourself and see what it produces

Task 3: Update our infrastructure

Section titled “Task 3: Update our infrastructure”

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

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

Task 4: Build the code

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

Using the command line, run the following command to fix any lint issues first:

Terminal window
pnpm lint

Then, run the following command for a full build:

Terminal window
pnpm build

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 build artifacts 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. 🎉🎉🎉