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#cloudscape-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#cloudscape-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: Define Cloud Resources and Deploy to AWS

Section titled “Step 3: 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

Step 4: Run the Frontend Locally

Section titled “Step 4: Run the Frontend Locally”

  1. Fetch the runtime-config.json file:

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

  2. Start the local website server

    Terminal window
    pnpm nx run @demo/demo-website:serve

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

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