Quick Start Guide

This guide walks you through the basics of installing and using @aws/nx-plugin to rapidly build projects on AWS.

Full-Stack Tutorial

For a more in-depth tutorial for building a full-stack application, check out the Dungeon Adventure Tutorial.

Prerequisites

The following global dependencies are needed before proceeding:

Required

• Git
• Node >= 22 (We recommend using something like NVM to manage your node versions)
  • verify by running node --version
• UV >= 0.5.29
  1. install Python 3.14 by running: uv python install 3.14.0
  2. verify with uv python list --only-installed

Recommended

• PNPM >= 11 (you can also use Yarn >= 4, Bun >= 1, or NPM >= 10 if you prefer)
  • verify by running pnpm --version, yarn --version, bun --version or npm --version
• AWS Credentials configured to your target AWS account are required to deploy your application (as well as for some local development workflows).
• Docker or Finch >= 1.6.0 is required for some generators. For Docker, multi-platform builds must be set up; Finch supports multi-platform builds out of the box.
• Terraform >= 1.12 is required if you choose to use this for infrastructure as code instead of CDK
  • verify by running terraform --version
• If you are using VSCode, we recommend installing the Nx Console VSCode Plugin.

AI Assistant Setup

If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, you may also wish to install the Nx Plugin for AWS MCP server.

Step 1: Initialize a New Nx Workspace

Run the following command to create an Nx workspace with the package manager of your choice:

pnpm

pnpm create @aws/nx-workspace my-project

yarn

yarn create @aws/nx-workspace my-project

npm

npm create @aws/nx-workspace -- my-project

bun

bun create @aws/nx-workspace my-project

Choosing an IaC Provider

You will be prompted for your preferred infrastructure as code (IaC) provider, either CDK or Terraform. You can skip the prompt by running the command with --iac, ie:

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

Once complete, navigate to the project directory:

cd my-project

Step 2: Use Generators to Scaffold your Project

We’ll add a tRPC API, React Website, Cognito Authentication, and CDK or Terraform Infrastructure in this quick-start guide. Depending on the type of project you’re building, you can choose any combination of generators to quickly bootstrap your project. Check out the Generators in the navigation bar to the left to see the full list of options, or try the graph builder to construct your workspace visually.

As a shortcut, you can use the button below to copy the commands to scaffold the full application.

Loading the diagram…

Build with AI

The Nx Plugin for AWS MCP Server is already configured in your workspace, so you can ask your favourite AI coding agent like Kiro or Claude to build these projects for you instead of typing the CLI commands yourself.

Otherwise, follow the steps below to run each generator yourself.

Add a tRPC API

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

VSCode

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#api
5. Fill in the required parameters
   • name: demo-api
   • framework: trpc
   • auth: iam
6. Click Generate

This will create the API inside the packages/demo-api folder.

Add a React Website

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

VSCode

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#website
5. Fill in the required parameters
   • name: demo-website
6. Click Generate

This scaffolds a new React website in packages/demo-website.

Add Cognito Authentication

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

VSCode

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#website#auth
5. Fill in the required parameters
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Click Generate

This sets up the necessary infrastructure and React code to add Cognito Authentication to your website.

Connect Frontend to Backend

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

VSCode

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 - connection
5. Fill in the required parameters
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Click Generate

This configures the necessary providers to ensure your website can call your tRPC API.

Add Infrastructure

Add the infrastructure project based on your chosen IAC provider.

CDK

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

VSCode

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

This configures a CDK App which you can use to deploy your infrastructure on AWS.

Terraform

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

VSCode

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 - terraform#project
5. Fill in the required parameters
   • name: infra
6. Click Generate

This configures a Terraform project which you can use to deploy your infrastructure on AWS.

Step 3: Run your Website and API Locally

Use the following command to start local dev servers for your website and its connected APIs:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Your website will be available at http://localhost:4200.

Changes to both your website and API will be reflected in real-time as both the local website and API servers will hot-reload.

Step 4: Define Cloud Resources and Deploy to AWS

CDK

Open packages/infra/src/stacks/application-stack.ts and add the following code:

import { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

This is all the CDK we need to write to deploy our full stack application.

Terraform

Open packages/infra/src/main.tf and add the following code:

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Deploy website
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

This is all the Terraform we need to write to deploy our full stack application.

Build and Deploy the Infrastructure

Next, run the following command to build your project:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Fixing Lint Errors

If you encounter any lint errors, you can run the following command to automatically fix them.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Bootstrap your infrastructure:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Bootstrap Regions

CDK bootstrapping is required for both your target deployment AWS region, and us-east-1 to allow deployment of the AWS WAF WebACL for the website.

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

One-Time Setup

Terraform bootstrapping creates an S3 bucket to store your Terraform state files. This only needs to be done once per AWS account/region combination.

Deploy your project:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Plan Before Apply

This command will first run terraform plan to show you what changes will be made, then apply those changes to deploy your infrastructure.

Step 5: Test the Website with Deployed Cloud Resources

1. Fetch the runtime-config.json file:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. Start the local website server

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

Your website will be available at http://localhost:4200, and will point to the resources you deployed for the API and authentication.

---

Congratulations! 🎉 You have successfully built and deployed a full-stack application using @aws/nx-plugin!