Skip to content
@aws/nx-plugin
Blog

Quick Start Guide

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

Prerequisites

Section titled “Prerequisites”

The following global dependencies are needed before proceeding:

  • 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)
  • If you are using VSCode, we recommend installing the Nx Console VSCode Plugin.

Step 1: Initialize a New Nx Workspace

Section titled “Step 1: Initialize a New Nx Workspace”

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

Terminal window
npx create-nx-workspace@~21.0.3 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip

Once complete, navigate to the project directory:

Terminal window
cd my-project

Step 2: Use Generators to Scaffold your Project

Section titled “Step 2: Use Generators to Scaffold your Project”

We’ll add a tRPC API, React Website, Cognito Authentication, and CDK 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

Section titled “Add a tRPC 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 - ts#trpc-api
  5. Fill in the required parameters
    • name: demo-api
    • auth: IAM
  6. Click Generate

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

Add a React Website

Section titled “Add a React Website”
  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

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

Add Cognito Authentication

Section titled “Add Cognito Authentication”
  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

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

Connect Frontend to Backend

Section titled “Connect Frontend to Backend”
  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

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

Add CDK Infrastructure

Section titled “Add 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

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

Step 3: Run your Website and API Locally

Section titled “Step 3: Run your Website and API Locally”

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

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

Section titled “Step 4: Define Cloud Resources and Deploy to AWS”

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.

Build and Deploy the Infrastructure

Section titled “Build and Deploy the Infrastructure”

Next, run the following command to build your project:

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

Run the following command to deploy your project:

Terminal window
pnpm nx run infra:deploy --all

Step 5: Test the Website with Deployed Cloud Resources

Section titled “Step 5: Test the Website with Deployed Cloud Resources”

  1. Fetch the runtime-config.json file:

    Terminal window
    pnpm nx run demo-website:load:runtime-config

  2. Start the local website server

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