React Website

This generator creates a new React website with CloudScape configured, 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.

Note

While this generator sets you up with CloudScape, it is ultimately a React project generator, and you can modify your code to move to an alternative design system or component library should you wish.

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

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-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 --dry-run

yarn

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

npm

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

bun

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

Options

Parameter	Type	Default	Description
name Required	string	-	The name of the application.
directory	string	packages	The directory of the new application.
enableTailwind	boolean	true	Enable TailwindCSS for utility-first styling.
enableTanstackRouter	boolean	true	Enable Tanstack router for type-safe routing.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 CloudScape layout and navigation bar
  • Directoryhooks

    • useAppLayout.tsx Hook for adjusting the AppLayout from nested components
  • Directoryroutes

    • Directorywelcome

      • index.tsx Example route (or page) for @tanstack/react-router
  • styles.css Global styles
• vite.config.ts 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

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

Note

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

Note

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

Implementing your React Website

The React documentation is a good place to start to learn the basics of building with React. You can refer to the CloudScape documentation for details about the available components and how to use them.

Routes

Creating a Route/Page

Your CloudScape 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#trpc-api and py#fast-api) will automatically add appropriate values to the RuntimeConfig.

Your website CDK construct will deploy 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 } from ':my-scope/common-constructs';

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

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

    // Automatically deploys the runtime config to runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

Caution

You must ensure that you declare your website after any constructs which add to the RuntimeConfig, otherwise they will be missing in your runtime-config.json file.

Terraform

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

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

packages/infra/src/main.tf

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

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

Caution

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;
};

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"

Note

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

You can run a local development server using either the serve or serve-local target.

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 run <my-website>:serve

yarn

yarn nx run <my-website>:serve

npm

npx nx run <my-website>:serve

bun

bunx nx run <my-website>:serve

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

Serve Local Target

The serve-local target starts a local development server for your website (with Vite MODE set to serve-local), as well as starting any local servers for APIs you have connected your website to via the API 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 run <my-website>:serve-local

yarn

yarn nx run <my-website>:serve-local

npm

npx nx run <my-website>:serve-local

bun

bunx nx run <my-website>:serve-local

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

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

To enable login and authentication for serve-local, deploy your infrastructure and load runtime config.

Building

You can build your website using the build target. This use Vite to create a production bundle in the root dist/packages/<my-website>/bundle directory, as well as type-checking, compiling and linting your website.

pnpm

pnpm nx run <my-website>:build

yarn

yarn nx run <my-website>:build

npm

npx nx run <my-website>:build

bun

bunx nx run <my-website>:build

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 run <my-website>:test

yarn

yarn nx run <my-website>:test

npm

npx nx run <my-website>:test

bun

bunx nx run <my-website>:test

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

Note

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"
}