Quick Start Guide

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

Tip

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
• PNPM >= 10 (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
• UV >= 0.5.29
  1. install Python 3.12 by running: uv python install 3.12.0
  2. verify with uv python list --only-installed
• AWS Credentials configured to your target AWS account (where your application will be deployed)

Recommended

• Docker is required for some generators.
• 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.

Tip

If you use an AI Assistant such as Kiro, Amazon Q Developer, 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

npx create-nx-workspace@21.6.8 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip --aiAgents

yarn

npx create-nx-workspace@21.6.8 my-project --pm=yarn  --preset=@aws/nx-plugin --ci=skip --aiAgents

npm

npx create-nx-workspace@21.6.8 my-project --pm=npm  --preset=@aws/nx-plugin --ci=skip --aiAgents

bun

npx create-nx-workspace@21.6.8 my-project --pm=bun  --preset=@aws/nx-plugin --ci=skip --aiAgents

Tip

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 --iacProvider, ie:

CDK

pnpm

npx create-nx-workspace@21.6.8 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

yarn

npx create-nx-workspace@21.6.8 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

npm

npx create-nx-workspace@21.6.8 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

bun

npx create-nx-workspace@21.6.8 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

Terraform

pnpm

npx create-nx-workspace@21.6.8 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

yarn

npx create-nx-workspace@21.6.8 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

npm

npx create-nx-workspace@21.6.8 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

bun

npx create-nx-workspace@21.6.8 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

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 Guides in the navigation bar to the left to see the full list of options.

Add a tRPC API

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

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

Add a React Website

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Add Cognito Authentication

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Connect Frontend to Backend

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --dry-run

yarn

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

npm

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

bun

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

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

Terraform

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --dry-run

yarn

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

npm

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

bun

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

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 nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

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 * as cdk from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.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"
}

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

# 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 nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Tip

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

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

Bootstrap your infrastructure:

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Tip

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 run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Tip

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 run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

Tip

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 run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. Start the local website server

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

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!