Quick Start Guide

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

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
  2. verify with uv python list --only-installed

Recommended

• PNPM >= 11 (you can also use Yarn >= 4, Bun >= 1, or NPM >= 11 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.

Step 1: Create a Workspace

Create an Nx workspace with the package manager of your choice, and open the directory it creates:

Create your workspace@aws/nx-workspace

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

Build your command3

workspaceRequired

iac

cdkterraform

containers

inferdockerfinch

cd my-project

You are prompted to choose your infrastructure as code provider, either CDK or Terraform.

Step 2: Build Your Application

We’ll build a full-stack application: a tRPC API, a React website, Cognito authentication, and CDK or Terraform infrastructure. Ask an AI assistant to scaffold it for you, or run the generators yourself — both routes reach the same workspace.

With AI

1. Open the workspace in your AI coding assistant.

   New workspaces come with the plugin’s MCP server already configured for Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot and OpenAI Codex, so your assistant can look up the plugin’s generators and run them without any setup.

2. Ask for the application:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   Your assistant discovers the generators through the MCP server and runs them, in the order their dependencies need. Review the changes it makes, then carry on at Step 3.

With the CLI

Run the generators that scaffold the application. Use the button below to copy them all, or run each one yourself as described beneath the diagram.

CDK

Loading the diagram…

Terraform

Loading the diagram…

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.

Add a tRPC API

Run this generator@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

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
6. Click Generate

Options for this step2

nameRequired

framework

trpc

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

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

Add a React Website

Run this generator@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

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
6. Click Generate

Options for this step1

nameRequired

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

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

Add Cognito Authentication

Run this generator@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

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
6. Click Generate

Options for this step1

projectRequired

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

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

Connect Frontend to Backend

Run this generator@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

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
6. Click Generate

Options for this step2

sourceProjectRequired

targetProjectRequired

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

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

Run this generator@aws/nx-plugin:ts#infra

CLI

pnpm

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

yarn

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

npm

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

bun

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

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
6. Click Generate

Options for this step1

nameRequired

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

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

Terraform

Run this generator@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

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
6. Click Generate

Options for this step1

nameRequired

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

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.

Try it: call the API from your website

Step 4: Define Cloud Resources and Deploy to AWS

CDK

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

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } 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 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:

# 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]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

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 and Formatting Errors

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

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

The workspace is out of sync

If the build reports The workspace is out of sync, accept the prompt to sync the workspace or run the following sync command directly before retrying the build:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

This writes the TypeScript project references and package.json dependency entries your imports require.

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. If you are deploying elsewhere, bootstrap us-east-1 too:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

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.

To sign in, you will need to create a user in the Cognito user pool.

Click here for instructions using the AWS CLI

Your website is also served from CloudFront. Open its distribution domain name (which is printed to your terminal after deployment) to use the version running entirely on AWS.

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

Step 6: Clean Up

When you have finished, delete the resources you deployed to avoid ongoing costs:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

Retained Resources

The Cognito user pool is created with deletion protection enabled, so it is not removed automatically. Delete it (and the IAM role Cognito uses to send SMS messages) manually if you no longer need them.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Retained Resources

The Cognito user pool is created with deletion protection enabled, so it is not removed automatically (the destroy command will report a failure). Delete it (and the IAM role Cognito uses to send SMS messages) manually if you no longer need them.

To remove bootstrap resources, follow below:

CDK

Delete the bootstrap stack in every region you bootstrapped, including us-east-1. This removes the bootstrap roles and the container image repository:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

Asset Bucket

The asset bucket is retained on purpose, so delete it separately.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Your Terraform State Is Deleted Too

This empties and deletes the S3 bucket holding your Terraform state, so only run it once you have torn down all deployed infrastructure.

---

Next Steps

• Dungeon Adventure Tutorial — build a full-stack AI dungeon adventure game, for a more in-depth walkthrough than this guide.
• Workspaces — how your workspace is laid out, and the configuration the generators share.
• Add to an Existing Project — adopt the plugin in your existing codebase.