@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/react-website.mdx

@@ -0,0 +1,421 @@
+---
+title: React Website
+description: Reference documentation for a React Website
+generator: ts#react-website
+---
+import { FileTree, Steps } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+This generator creates a new [React](https://react.dev/) website with [Cloudscape](http://cloudscape.design/) 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](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
+
+The generated application uses [Vite](https://vite.dev/) as the build tool and bundler. It uses [TanStack Router](https://tanstack.com/router/v1) for type-safe routing.
+
+:::note[UX Provider]
+The default `uxProvider` is [Cloudscape](http://cloudscape.design/). You can also select [shadcn/ui](https://ui.shadcn.com/) or `None` (bring your own component library).
+:::
+
+## Usage
+
+### Generate a React Website
+
+You can generate a new React Website in two ways:
+
+<RunGenerator generator="ts#react-website" />
+
+### Options
+
+<GeneratorParameters generator="ts#react-website" />
+
+## Generator Output
+
+The generator will create the following project structure in the `<directory>/<name>` directory:
+
+<FileTree>
+  - index.html HTML entry point
+  - public Static assets
+  - src
+    - main.tsx Application entry point with React setup
+    - config.ts Application configuration (eg. logo)
+    - components
+      - AppLayout Components for the overall layout and navigation bar
+    - hooks
+      - useAppLayout.tsx Hook for adjusting the AppLayout from nested components (Cloudscape only)
+    - routes
+      - 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
+</FileTree>
+
+:::note[Without TanStack Router]
+If you opted not to use [TanStack Router](https://tanstack.com/router/v1), you will be vended a simple `src/app.tsx` file as your application entry point instead of the `routes` directory.
+:::
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+The generator creates infrastructure as code for deploying your website based on your selected `iacProvider`:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - static-websites
+        - \<name>.ts Infrastructure specific to your website
+    - core
+      - static-website.ts Generic StaticWebsite construct
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - static-websites
+        - \<name>
+          - \<name>.tf Module specific to your website
+    - core
+      - static-website
+        - static-website.tf Generic static website module
+</FileTree>
+</Fragment>
+</Infrastructure>
+
+#### Architecture
+
+The deployed website has the following architecture:
+
+```d2 inline=true
+direction: right
+
+browser: Web Browser {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+waf: WAF {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/waf.svg
+}
+
+cloudfront: CloudFront {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudfront.svg
+}
+
+s3: Static Assets\n(S3) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/s3.svg
+}
+
+browser -> waf
+waf -> cloudfront
+cloudfront -> s3
+```
+
+## Implementing your React Website
+
+The [React documentation](https://react.dev/learn) is a good place to start to learn the basics of building with React.
+
+<OptionFilter when={{ uxProvider: 'Cloudscape' }} description="Cloudscape component docs pointer">
+You can refer to the [Cloudscape documentation](https://cloudscape.design/components/) for details about the available components and how to use them.
+</OptionFilter>
+
+<OptionFilter when={{ uxProvider: 'Shadcn' }} description="Shadcn component docs pointer">
+You can refer to the [shadcn/ui documentation](https://ui.shadcn.com/docs) for details about the available components and how to use them.
+</OptionFilter>
+
+### Routes
+
+#### Creating a Route/Page
+
+Your website comes with [TanStack Router](https://tanstack.com/router/v1) configured by default. This makes it easy to add new routes:
+
+<Steps>
+  1. [Run the Local Development Server](#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!
+</Steps>
+
+#### Navigating Between Pages
+
+You can use the `Link` component or `useNavigate` hook to navigate between pages:
+
+```tsx {1, 4, 8-9, 14}
+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](https://tanstack.com/router/latest/docs/framework/react/overview) documentation.
+
+## Runtime Configuration
+
+Configuration from your infrastructure is provided to your website via <Link href="guides/runtime-config">Runtime Configuration</Link>. This allows your website to access details such as API URLs which are not known until your application is deployed.
+
+### Infrastructure
+
+<Infrastructure>
+<Fragment slot="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 <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) 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.
+
+```ts title="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(),
+    });
+  }
+}
+```
+
+:::note[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.
+:::
+</Fragment>
+<Fragment slot="terraform">
+With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) 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.
+
+```hcl title="packages/infra/src/main.tf" {18-19}
+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]
+}
+```
+
+:::caution[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.
+:::
+</Fragment>
+</Infrastructure>
+
+### Website Code
+
+In your website, you can use the `useRuntimeConfig` hook to retrieve values from the runtime configuration:
+
+```tsx {1,4}
+import { useRuntimeConfig } from '../hooks/useRuntimeConfig';
+
+const MyComponent = () => {
+  const runtimeConfig = useRuntimeConfig();
+
+  // Access values in the runtime config here
+  const apiUrl = runtimeConfig.apis.MyApi;
+};
+```
+
+:::note[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 <Link path="guides/runtime-config">Runtime Configuration</Link> guide.
+:::
+
+### Local Runtime Config
+
+When running the [local development server](#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:
+
+<NxCommands commands={['run <my-website>:"load:runtime-config"']} />
+
+:::note[Custom Stage Names]
+<Infrastructure>
+<Fragment slot="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.
+</Fragment>
+<Fragment slot="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`.
+</Fragment>
+</Infrastructure>
+:::
+
+## 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](#local-runtime-config).
+
+You can run this target with the following command:
+
+<NxCommands commands={['serve <my-website>']} />
+
+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`](https://vite.dev/guide/env-and-mode) set to `serve-local`), as well as starting any local servers for APIs you have connected your website to via the <Link path="/guides/connection">Connection generator</Link>.
+
+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:
+
+<NxCommands commands={['serve-local <my-website>']} />
+
+This target is useful when you are working across your website and API and wish to quickly iterate without deploying your infrastructure.
+
+:::note[`dev` script]
+If no `dev` script exists in your root `package.json` when this generator runs, a `dev` script is added that invokes `serve-local` for the generated website, meaning you can also start the local development server with:
+
+<PackageManagerShortCommand commands={["dev"]} />
+
+This makes the first React website you generate the default `dev` target for the workspace. Subsequent websites do not overwrite the existing `dev` script — you can invoke their `serve-local` targets directly, or update the script manually.
+:::
+
+:::warning[Mock Authentication]
+When run in this mode and no `runtime-config.json` is present, if you have configured Cognito Authentication (via the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>), 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.
+:::
+
+:::tip[Serve-Local Behavior]
+When running with `serve-local`, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:
+
+<NxCommands env={{DYNAMODB_TABLE_NAME: 'xxxxx'}} commands={['serve-local <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 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.
+
+<NxCommands commands={['build <my-website>']} />
+
+## Testing
+
+Testing your website is much like writing tests in a standard TypeScript project, so please refer to the <Link path="guides/typescript-project#testing">TypeScript project guide</Link> 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](https://testing-library.com/docs/react-testing-library/example-intro).
+
+You can run your tests using the `test` target:
+
+<NxCommands commands={['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.
+
+<Infrastructure>
+<Fragment slot="cdk">
+To deploy your website, we recommend using the <Link path="guides/typescript-infrastructure">`ts#infra` generator</Link> to create a CDK application.
+
+You can use the CDK construct generated for you in `packages/common/constructs` to deploy your website.
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {3, 9}
+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
+</Fragment>
+<Fragment slot="terraform">
+To deploy your website, we recommend using the <Link path="guides/terraform-infrastructure">`terraform#project` generator</Link> to create a Terraform project.
+
+You can use the Terraform module generated for you in `packages/common/terraform` to deploy your website.
+
+```hcl title="packages/infra/src/main.tf" {3}
+# 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[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:
+
+```hcl title="packages/infra/src/providers.tf"
+provider "aws" {
+  alias  = "us_east_1"
+  region = "us-east-1"
+}
+```
+:::
+</Fragment>
+</Infrastructure>
+