Skip to content
@aws/nx-plugin
Blog

CloudScape Website

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

Usage

Generate a CloudScape Website

You can generate a new CloudScape Website in two ways:

  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
    • Click Generate

    Options

    Parameter Type Default Description
    name required string - The name of the application.
    directory string packages The directory of the new application.

    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

    The generator will also create CDK infrastructure code for deploying your website in the packages/common/constructs directory:

    • Directorysrc
      • Directoryapp
        • Directorystatic-websites
          • <name>.ts Infrastructure specific to your website
      • Directorycore
        • static-website.ts Generic StaticWebsite construct

    Implementing your CloudScape 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. 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!

    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 AWS CDK 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

    The RuntimeConfig CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by @aws/nx-plugin (such as tRPC APIs and FastAPIs) 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');
    

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

    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.

    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.httpApis.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:

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

    If you change the name of your stack 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 with the name of the stack to load runtime configuration from.

    Local Development Server

    Before running your local development server, make sure that you have deployed your infrastructure and have loaded local runtime configuration.

    You can then run the serve target:

    Terminal window
    pnpm nx run <my-website>:serve

    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.

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

    Terminal window
    pnpm nx run <my-website>:test

    Deploying Your Website

    To deploy your website, we recommend using the TypeScript Infrastructure 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');
      }
    }