React Website

This generator creates a new React website with shadcn/ui configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in S3, served by CloudFront and protected by WAF.

The generated application uses Vite as the build tool and bundler. It uses TanStack Router for type-safe routing.

UX Provider

The default uxProvider is shadcn/ui. You can also select Cloudscape or None (bring your own component library).

Usage

Generate a React Website

You can generate a new React Website in two ways:

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
   • framework: react
6. Click Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Options

Parameter	Type	Default	Description
name Required	string	-	The name of the application.
framework	react	react	The frontend framework to use.
directory	string	packages	The directory of the new application.
subDirectory	string	-	The sub directory the project is placed in. By default this is the project name.
ux	none | cloudscape | shadcn	shadcn	The preferred UX provider.
tailwind	boolean	true	Enable TailwindCSS for utility-first styling.
tanstackRouter	boolean	true	Enable Tanstack router for type-safe routing.
infra	cloudfront-s3 | none	cloudfront-s3	The type of infrastructure to deploy your website with.
iac	inherit | cdk | terraform	inherit	The preferred IaC provider. By default this is inherited from your initial selection.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator will create the following project structure in the <directory>/<name> directory:

• index.html HTML entry point
• public Static assets
• Directorysrc

  • main.tsx Application entry point with React setup
  • config.ts Application configuration (eg. logo)
  • Directorycomponents

    • AppLayout Components for the overall layout and navigation bar
  • Directoryhooks

    • useAppLayout.tsx Hook for adjusting the AppLayout from nested components (Cloudscape only)
  • Directoryroutes

    • index.tsx Example route (or page) for TanStack Router
  • styles.css Global styles
• vite.config.mts Vite and Vitest configuration
• tsconfig.json Base TypeScript configuration for source and tests
• tsconfig.app.json TypeScript configuration for source code
• tsconfig.spec.json TypeScript configuration for tests

Without TanStack Router

If you opted not to use TanStack Router, you will be vended a simple src/app.tsx file as your application entry point instead of the routes directory.

Infrastructure

Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

This project is generated using the terraform#project generator and therefore configures the same build targets.

The generator creates infrastructure as code for deploying your website based on your selected iacProvider:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts Infrastructure specific to your website
  • Directorycore

    • static-website.ts Generic StaticWebsite construct

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<name>

        • <name>.tf Module specific to your website
  • Directorycore

    • Directorystatic-website

      • static-website.tf Generic static website module

Architecture

The deployed website has the following architecture:

Security Headers

The CloudFront distribution applies a response headers policy that sets Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy and a Content-Security-Policy on all responses.

A default Content-Security-Policy is enforced. It restricts scripts and framing to mitigate XSS and clickjacking, while permitting HTTPS and WSS connections so the website can call AWS service endpoints (such as API Gateway, Cognito and Bedrock AgentCore) whose URLs are only known at deploy time. To adjust the policy (for example to tighten connect-src to your specific origins), edit the content_security_policy value in your generated static-website.ts (CDK) or static-website.tf (Terraform).

runtime-config.json is served with Cache-Control: no-cache so that browsers always fetch the latest configuration after a redeploy, rather than using a stale cached copy.

Implementing your React Website

The React documentation is a good place to start to learn the basics of building with React.

ux = cloudscape

You can refer to the Cloudscape documentation for details about the available components and how to use them.

ux = shadcn

You can refer to the shadcn/ui documentation for details about the available components and how to use them.

Routes

Creating a Route/Page

Your website comes with TanStack Router configured by default. This makes it easy to add new routes:

1. Run the Local Development Server
2. Create a new <page-name>.tsx file in src/routes, with its position in the file tree representing the path
3. Notice a Route and RouteComponent are automatically generated for you. You can start building your page here!

Navigating Between Pages

You can use the Link component or useNavigate hook to navigate between pages:

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // Use `navigate` for redirecting after some asynchronous action
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">Cancel</Link>
      <Button onClick={submit}>Submit</Button>
    </>
  )
};

For more details, check out the TanStack Router documentation.

Runtime Configuration

Configuration from your infrastructure is provided to your website via Runtime Configuration. This allows your website to access details such as API URLs which are not known until your application is deployed.

Infrastructure

CDK

The RuntimeConfig CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by @aws/nx-plugin generators (such as ts#api and py#api) will automatically add appropriate values to the RuntimeConfig.

Your website CDK construct will deploy the connection namespace of the runtime configuration as a runtime-config.json file to the root of your S3 bucket.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, MyApi } from ':my-scope/common-constructs';

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

    // Website can be declared at any point — runtime config is resolved lazily
    new MyWebsite(this, 'MyWebsite');

    // Automatically adds values to the RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

CDK Website Construct

With CDK, the website construct can be declared at any point in your stack. Runtime configuration is resolved lazily at synth time, so all values will be included regardless of declaration order.

Terraform

With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by @aws/nx-plugin generators (such as ts#api and py#api) will automatically add appropriate values to the runtime configuration.

Your website Terraform module will deploy the connection namespace of the runtime configuration as a runtime-config.json file to the root of your S3 bucket.

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Automatically adds values to runtime config
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Automatically deploys the runtime config to runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Ensure API is deployed first to add to runtime config
  depends_on = [module.my_api]
}

Module Ordering

You must ensure that you declare your website module after any modules which add to the runtime configuration and configure the appropriate depends_on to ensure ordering, otherwise they will be missing in your runtime-config.json file.

Website Code

In your website, you can use the useRuntimeConfig hook to retrieve values from the runtime configuration:

import { useRuntimeConfig } from '../hooks/useRuntimeConfig';

const MyComponent = () => {
  const runtimeConfig = useRuntimeConfig();

  // Access values in the runtime config here
  const apiUrl = runtimeConfig.apis.MyApi;
};

Runtime Configuration

For details on how runtime configuration is stored in AWS AppConfig and how server-side consumers (Lambda functions, agents) can retrieve it, see the Runtime Configuration guide.

Local Runtime Config

When running the local development server, you will need a runtime-config.json file in your public directory in order for your local website to know the backend URLs, identity configuration, etc.

Your website project is configured with a load:runtime-config target which you can use to pull down the runtime-config.json file from a deployed application:

pnpm

pnpm nx run <my-website>:"load:runtime-config"

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

Custom Stage Names

CDK

If you change the prefix for your stage names in your infrastructure project’s src/main.ts, you will need to update the load:runtime-config target in your website’s project.json file accordingly.

Additionally it’s worth noting that the load:runtime-config target assumes a single stage of your application is deployed to the environment you have AWS credentials for. You will need to adjust the command if you deploy multiple stages to the same account and region.

Terraform

For Terraform projects, the load:runtime-config target copies the runtime-config.json file that was created after your most recent local terraform apply.

Local Development Server

The canonical command for local development is dev, which starts your website (and any local servers for APIs you’ve connected it to) with one command:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

The serve target is also available for when you need to control how much of your application runs locally versus pointing at deployed AWS infrastructure. For a broader overview of local development across connected projects, including how dev behaves for projects with multiple components, see the Local Development guide.

Serve Target

The serve target starts a local development server for your website. This target requires you to have deployed any supporting infrastructure that the website interacts with, and have loaded local runtime configuration.

You can run this target with the following command:

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

This target is useful for working on website changes while pointing to “real” deployed APIs and other infrastructure.

Dev Target

The dev target starts a local development server for your website (with Vite MODE set to local-dev), as well as starting any local servers for APIs you have connected your website to via the Connection generator.

When your local website server is run via this target, runtime-config.json is automatically overridden to point to your locally running API urls.

You can run this target with the following command:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

This target is useful when you are working across your website and API and wish to quickly iterate without deploying your infrastructure.

Workspace dev script

Your workspace’s root package.json includes a dev script that runs the dev target for every project that has one:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

This starts the local development server for your website (and any other projects with a dev target) in one command. To run just this website, use its own dev target (e.g. nx dev <my-website>).

Mock Authentication

When run in this mode and no runtime-config.json is present, if you have configured Cognito Authentication (via the ts#website#auth generator), login will be skipped and requests to your local servers will not include authentication headers.

To enable login and authentication for dev, deploy your infrastructure and load runtime config.

Dev Behavior

When running with dev, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <my-website>

Note that your local API servers will run with the AWS credentials you have configured locally.

Building

You can build your website using the build target. This runs the bundle, compile, test and lint targets, type-checking, bundling, testing and linting your website.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

The bundle target uses Vite to create a production bundle in the root dist/packages/<my-website>/bundle directory. This is the deployable artifact consumed by your website infrastructure. You can run it on its own:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

Testing

Testing your website is much like writing tests in a standard TypeScript project, so please refer to the TypeScript project guide for more details.

For React specific testing, React Testing Library is already installed and available for you to use to write tests. For more details on its usage, please refer to the React Testing Library documentation.

You can run your tests using the test target:

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

Deploying Your Website

The React website generator creates CDK or Terraform infrastructure as code based on your selected iacProvider. You can use this to deploy your website.

CDK

To deploy your website, we recommend using the ts#infra generator to create a CDK application.

You can use the CDK construct generated for you in packages/common/constructs to deploy your website.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

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

    new MyWebsite(this, 'MyWebsite');
  }
}

This sets up:

1. An S3 bucket for hosting your static website files
2. CloudFront distribution for global content delivery
3. WAF Web ACL for security protection
4. Origin Access Control for secure S3 access
5. Automatic deployment of website files and runtime configuration

Terraform

To deploy your website, we recommend using the terraform#project generator to create a Terraform project.

You can use the Terraform module generated for you in packages/common/terraform to deploy your website.

packages/infra/src/main.tf

# Deploy website
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

This sets up:

1. An S3 bucket for hosting your static website files
2. CloudFront distribution for global content delivery
3. WAF Web ACL for security protection (deployed in us-east-1)
4. Origin Access Control for secure S3 access
5. Automatic deployment of website files and runtime configuration

WAF Provider Region

The aws.us_east_1 provider is required for CloudFront and WAF resources, which must be deployed in the us-east-1 region. Make sure your Terraform configuration includes this provider:

packages/infra/src/providers.tf

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

Connections

Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

React to tRPCCall a tRPC API from a React website

React to FastAPICall a Python FastAPI from a React website

React to Smithy APICall a Smithy API from a React website

React to Python AgentCall a Python Agent from a React website

React to TypeScript AgentCall a TypeScript Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit