@aws/nx-plugin 0.26.0 → 0.28.0

package/src/cloudscape-website/app/README.md

@@ -1,289 +0,0 @@
-# Cloudscape Website App Generator
-
-## Overview
-
-This generator creates a new Cloudscape React application with AWS CDK infrastructure setup. The generated application uses Vite as the build tool and bundler, providing fast development and optimized production builds. The codebase is structured using ES Modules (ESM) for modern JavaScript module system compatibility. It sets up a complete web application using AWS Cloudscape Design System components and configures the necessary build tools and dependencies.
-
-## Usage
-
-You can generate a new Cloudscape website application in two ways:
-
-### 1. Using VSCode IDE
-
-First, install the NX Console extension for VSCode:
-
-1. Open VSCode
-2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
-3. Search for "Nx Console"
-4. Install [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
-
-Then generate your application:
-
-1. Open the NX Console in VSCode
-2. Click on "Generate"
-3. Search for "ts#cloudscape-website"
-4. Fill in the required parameters in the form
-5. Click "Run"
-
-### 2. Using CLI
-
-Generate the application:
-
-```bash
-nx g @aws/nx-plugin:ts#cloudscape-website my-website --directory=apps/web
-```
-
-You can also perform a dry-run to see what files would be generated without actually creating them:
-
-```bash
-nx g @aws/nx-plugin:ts#cloudscape-website my-website --directory=apps/web --dry-run
-```
-
-Both methods will create a new Cloudscape website application in `apps/web/my-website` with all the necessary configuration and infrastructure code.
-
-## Input Parameters
-
-| Parameter      | Type    | Default    | Description                                                                                                                  |
-| -------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| name\*         | string  | -          | The name of the application (required). Must start with a letter and not contain colons.                                     |
-| directory      | string  | "packages" | The directory to store the application in.                                                                                   |
-| style          | string  | "css"      | The file extension for style files. Options: css, scss, less, tailwind, styled-components, @emotion/styled, styled-jsx, none |
-| unitTestRunner | string  | "vitest"   | Test runner for unit tests. Options: jest, vitest, none                                                                      |
-| bundler        | string  | "vite"     | The bundler to use. Options: vite, webpack, rspack                                                                           |
-| compiler       | string  | "swc"      | The compiler to use. Options: babel, swc                                                                                     |
-| linter         | string  | "eslint"   | The tool for running lint checks. Options: eslint, none                                                                      |
-| classComponent | boolean | false      | Use class components instead of functional components                                                                        |
-| strict         | boolean | true       | Creates an application with strict mode and strict type checking                                                             |
-| js             | boolean | false      | Generate JavaScript files instead of TypeScript files                                                                        |
-| minimal        | boolean | false      | Generate a React app with minimal setup, no separate test files                                                              |
-
-\*Required parameter
-
-## Expected Output
-
-The generator creates two main components:
-
-### 1. React Application Code
-
-```
-<directory>/<name>/
-├── src/
-│   ├── main.tsx           # Application entry point with React setup
-│   ├── config.ts          # Application configuration
-│   ├── layouts/           # Layout components
-│   └── pages/            # Page components for routing
-├── public/               # Static assets
-├── tsconfig.json        # TypeScript configuration
-├── vite.config.ts       # Vite bundler configuration
-├── project.json         # Project configuration and build targets
-└── index.html          # HTML entry point
-```
-
-### 2. Infrastructure Code
-
-```
-common/constructs/
-├── src/
-|   └── index.ts
-|   └── app/
-|   |   ├── index.ts
-|   |   └── static-websites
-|   |       └── index.ts
-|   |       └── <name>.ts      # Infrastructure specific to your website
-│   └── core/
-│       └── index.ts
-│       └── static-website.ts  # Contains the generic StaticWebsite construct
-├── tsconfig.json         # TypeScript configuration
-└── project.json         # Project configuration and build targets
-```
-
-Additionally, it:
-
-1. Configures build settings for production deployment
-2. Installs required dependencies:
-   - @cloudscape-design/components
-   - @cloudscape-design/board-components
-   - react-router-dom
-   - aws-cdk-lib
-   - constructs
-   - cdk-app-cli
-
-## Infrastructure Architecture
-
-```mermaid
-graph TD
-    subgraph AWS Cloud
-      CF --> WAF
-      subgraph ApplicationStack
-        CF[CloudFront Distribution] --> S3[S3 Bucket]
-        OAC[Origin Access Control] --> S3
-      end
-      subgraph "WafStack (us-east-1)"
-        WAF[WAF Rules]
-      end
-    end
-```
-
-The website construct deploys:
-
-1. **CloudFront Distribution**
-
-   - Global content delivery network
-   - Edge caching for static assets
-   - HTTPS enabled by default
-
-2. **S3 Bucket**
-
-   - Static website content hosting
-   - Private access through CloudFront
-   - Versioning enabled
-
-3. **WAF (Web Application Firewall)**
-
-   - Deployed as a seperate stack in us-east-1
-   - Web exploit protection
-   - Rate limiting
-   - IP-based filtering
-
-4. **Origin Access Control**
-   - Secure S3 bucket access
-   - Restricted to CloudFront only
-
-## Using the generated Construct
-
-After generating the application, you can use the generated construct in your CDK code:
-
-```typescript
-import { App, Stack } from 'aws-cdk-lib';
-import { MyWebsite /* Use you website specific name */ } from ':my-org/common-constructs';
-
-export class MyWebsiteStack extends Stack {
-  constructor(scope: App, id: string) {
-    super(scope, id);
-
-    new MyWebsite(this, 'MyWebsite');
-  }
-}
-```
-
-The website construct is pre-configured with:
-
-- S3 bucket for hosting website content
-- CloudFront distribution with Origin Access Control
-- WAF rules for security (deployed in us-east-1 via seperate stack)
-- Cross-region support for WAF configuration
-
-Since all the infrastructure code is generated in your project's `common/constructs` directory, you have full control to customize the implementation. The generated code serves as a starting point that you can adapt to your specific requirements.
-
-## Runtime Configuration
-
-The generator includes a RuntimeConfig system that bridges your infrastructure and frontend application. This system allows you to:
-
-1. **Share Configuration**: Pass runtime configuration from your infrastructure to your React application
-2. **Type Safety**: Configuration is fully typed using TypeScript interfaces
-3. **Context-Based Access**: Access configuration anywhere in your React components using React Context
-
-### Infrastructure Usage
-
-In your CDK code, you can set runtime configuration using the RuntimeConfig construct:
-
-```typescript
-import { RuntimeConfig } from ':my-org/common-constructs';
-
-export class MyWebsiteStack extends Stack {
-  constructor(scope: App, id: string) {
-    super(scope, id);
-
-    // Get or create the RuntimeConfig instance
-    const runtimeConfig = RuntimeConfig.ensure(this);
-
-    // Set configuration values
-    // Be sure to update the IRuntimeConfig interface first with your new definition
-    runtimeConfig.config.myFeature = {
-      apiEndpoint: 'https://api.example.com',
-      region: Stack.of(this).region,
-    };
-  }
-}
-```
-
-### Frontend Usage
-
-In your React components, you can access the runtime configuration using the RuntimeConfigContext:
-
-```typescript
-import { useRuntimeConfig } from './hooks/useRuntimeConfig';
-
-const MyComponent = () => {
-  const { myFeature } = useRuntimeConfig();
-
-  return (
-    <div>
-      <p>API Endpoint: {myFeature.apiEndpoint}</p>
-      <p>Region: {myFeature.region}</p>
-    </div>
-  );
-};
-```
-
-The RuntimeConfigProvider is automatically set up in your application's entry point:
-
-```typescript
-import RuntimeConfigProvider from './components/RuntimeConfig';
-
-const App = () => (
-  <RuntimeConfigProvider>
-    <RouterProvider router={router} />
-  </RuntimeConfigProvider>
-);
-```
-
-This configuration system is particularly useful when:
-
-- Integrating with AWS services that require runtime configuration (e.g., Cognito, API Gateway)
-- Managing environment-specific settings
-- Sharing infrastructure outputs with your frontend application
-
-## Building the Application
-
-### Development Build
-
-To run the application in development mode with hot-reload:
-
-```bash
-nx serve my-website
-```
-
-### Production Build
-
-To create a production build:
-
-```bash
-nx build my-website
-```
-
-All built code is located in the `dist` folder at the root of your workspace. For example, if your application is in `apps/web/my-website`, the built code will be in `dist/apps/web/my-website`.
-
-The production build:
-
-- Minifies JavaScript and CSS
-- Optimizes assets
-- Generates source maps
-- Creates a deployment-ready bundle
-
-## Local development
-
-Once you have deployed your application for the first time, we can pull down a copy of the `runtime-config.json` associated with the website so our local website server will operate as expected. To do this run the following command:
-
-```bash
-AWS_REGION=<YOUR_REGION> CDK_APP_DIR=<CDK_OUT_DIR>/cdk.out pnpm exec nx run @my-org/website:load:runtime-config
-```
-
-- **<YOUR_REGION>:** _the aws region you deployed into i.e: ap-southeast-2_
-- **<CDK_OUT_DIR>:** _the relative path (from the root) to the `cdk.out` directory._
-
-For example:
-
-```bash
-AWS_REGION=ap-southeast-2 CDK_APP_DIR=./dist/packages/infra/cdk.out pnpm exec nx run @my-org/website:load:runtime-config
-```

package/src/cloudscape-website/cognito-auth/README.md

@@ -1,193 +0,0 @@
-# Cognito Auth Generator
-
-## Overview
-
-This generator adds AWS Cognito authentication to an existing Cloudscape React application. It sets up the necessary components and infrastructure for user authentication using Amazon Cognito hosted UI, including sign-in, sign-up, and password recovery flows. The generator integrates seamlessly with the Cloudscape Design System components and configures all required AWS resources through CDK.
-
-## Prerequisites
-
-Before using this generator, ensure your project meets these requirements:
-
-1. The project must have a `main.tsx` file in its source directory
-2. The `main.tsx` file must contain a `<RuntimeConfigProvider>` element
-3. The project must be a valid Cloudscape application
-
-Example of required `main.tsx` structure:
-
-```typescript
-import { RuntimeConfigProvider } from './components/RuntimeConfig';
-
-const App = () => <RuntimeConfigProvider>{/* Your app components */}</RuntimeConfigProvider>;
-```
-
-If these prerequisites are not met, the generator will fail with an error.
-
-## Usage
-
-You can add Cognito authentication to your Cloudscape website in two ways:
-
-### 1. Using VSCode IDE
-
-First, install the NX Console extension for VSCode:
-
-1. Open VSCode
-2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
-3. Search for "Nx Console"
-4. Install [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
-
-Then add authentication:
-
-1. Open the NX Console in VSCode
-2. Click on "Generate"
-3. Search for "ts#cloudscape-website#cognito-auth"
-4. Fill in the required parameters:
-   - project: Your existing Cloudscape application name
-   - allowSignup: Whether to enable self-signup (optional)
-5. Click "Run"
-
-### 2. Using CLI
-
-Add authentication to your existing Cloudscape application:
-
-```bash
-nx g @aws/nx-plugin:ts#cloudscape-website#cognito-auth --project=my-cloudscape-app --cognito-domain=<your-domain-prefix>
-```
-
-Enable self-signup:
-
-```bash
-nx g @aws/nx-plugin:ts#cloudscape-website#cognito-auth --project=my-cloudscape-app --allowSignup=true --cognito-domain=<your-domain-prefix>
-```
-
-You can also perform a dry-run to see what files would be generated without actually creating them:
-
-```bash
-nx g @aws/nx-plugin:ts#cloudscape-website#cognito-auth --project=my-cloudscape-app --cognito-domain=<your-domain-prefix> --dry-run
-```
-
-All methods will add Cognito authentication to your existing Cloudscape website application with all the necessary components and infrastructure code.
-
-## Input Parameters
-
-| Parameter       | Type    | Default | Description                                                 |
-| --------------- | ------- | ------- | ----------------------------------------------------------- |
-| project\*       | string  | -       | The root directory of the Cloudscape application (required) |
-| cognitoDomain\* | string  | -       | domain prefix when creating the Cognito Hosted UI           |
-| allowSignup     | boolean | false   | Whether to allow self-signup                                |
-
-\*Required parameter
-
-## Expected Output
-
-The generator adds authentication-related components and infrastructure:
-
-### 1. React Components
-
-```
-<directory>/<websiteProject>/
-├── src/
-    └── components/
-    |   └── CognitoAuth/
-    |       └── index.tsx         # Main authentication component
-    └── layouts/
-        └── App/
-            └── index.tsx         # Updates this file to add auth support
-
-```
-
-### 2. Infrastructure Code
-
-```
-common
-    └── constructs/
-        └── src/
-            └── core/
-                └── index.ts              # Adds export for identity construct
-                └── user-identity.ts      # Main identity construct
-    └── types/
-        └── src/
-            └── runtime-config.ts         # Updates IRuntimeConfig to add cognitoProps
-```
-
-Additionally, it:
-
-1. Installs required dependencies:
-   - aws-cdk-lib
-   - constructs
-   - @aws-cdk/aws-cognito-identitypool-alpha
-   - react-oidc-context
-   - oidc-client-ts
-2. Updates the application's runtime configuration to include Cognito settings
-3. Automatically integrates the authentication component into your website code
-
-## Infrastructure Architecture
-
-```mermaid
-graph TD
-    subgraph AWS Cloud
-        UP[Cognito User Pool] --> IP[Identity Pool]
-        UP --> CognitoDomain
-        UP --> Client[Web Client]
-        IP --> IAM[IAM Roles]
-    end
-```
-
-The infrastructure stack adds:
-
-1. **Cognito User Pool**
-
-   - User directory management
-   - Sign-up and sign-in flows
-   - MFA configuration
-
-2. **Cognito Identity Pool**
-
-   - Federated identities
-   - AWS credentials mapping
-   - IAM role assignment
-
-3. **Web Client**
-
-   - User Password and SRP auth flows
-   - Token handling
-
-4. **Cognito Domain**
-   - Domain configured using the cognitoDomain provided
-
-## Authentication Components
-
-The generator automatically sets up authentication in your application by:
-
-1. Importing the CognitoAuth component in main.tsx
-2. Wrapping your application with the CognitoAuth component inside the RuntimeConfigProvider
-3. Configuring authenticated using the Cognito hosted UI
-4. Updating the layout add add a singout button and display the logged in user.
-
-No manual setup is required as the generator handles all the necessary component integration.
-
-## Runtime Configuration
-
-The generator automatically integrates with the RuntimeConfig system to provide Cognito configuration:
-
-### Infrastructure Usage
-
-```typescript
-import { UserIdentity } from ':my-org/common-constructs';
-import { Stack } from 'aws-cdk-lib';
-import { Construct } from 'constructs';
-
-export class MyWebsiteStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
-
-    // Create the Cognito authentication resources
-    new UserIdentity(this, 'Identity');
-
-    // The runtime config is automatically updated with Cognito settings
-  }
-}
-```
-
-### Frontend Usage
-
-The CognitoAuth component automatically uses the runtime configuration.

package/src/infra/app/README.md

@@ -1,200 +0,0 @@
-# Infrastructure App Generator
-
-## Overview
-
-This generator creates a new AWS CDK infrastructure application. The generated application includes security best practices through CFN guard checks. The codebase is structured using TypeScript and ES Modules (ESM) for modern development practices.
-
-## Usage
-
-You can generate a new infrastructure application in two ways:
-
-### 1. Using VSCode IDE
-
-First, install the NX Console extension for VSCode:
-
-1. Open VSCode
-2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
-3. Search for "Nx Console"
-4. Install [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
-
-Then generate your application:
-
-1. Open the NX Console in VSCode
-2. Click on "Generate"
-3. Search for "ts#infra"
-4. Fill in the required parameters in the form
-5. Click "Run"
-
-### 2. Using CLI
-
-Generate the application:
-
-```bash
-nx g @aws/nx-plugin:ts#infra my-infra --directory=apps/infrastructure
-```
-
-You can also perform a dry-run to see what files would be generated without actually creating them:
-
-```bash
-nx g @aws/nx-plugin:ts#infra my-infra --directory=apps/infrastructure --dry-run
-```
-
-## Input Parameters
-
-| Parameter      | Type   | Default         | Description                                                                              |
-| -------------- | ------ | --------------- | ---------------------------------------------------------------------------------------- |
-| name\*         | string | -               | The name of the application (required). Must start with a letter and not contain colons. |
-| ruleSet\*      | string | aws_prototyping | cfn guard ruleset to use                                                                 |
-| directory      | string | "packages"      | The directory to store the application in.                                               |
-| unitTestRunner | string | "vitest"        | Test runner for unit tests. Options: jest, vitest, none                                  |
-
-\*Required parameter
-
-## Expected Output
-
-The generator creates two main components:
-
-### 1. Infra app code
-
-```
-<directory>/<name>/
-├── src/
-│   └── main.ts           # Application entry point with CDK and PDK setup
-│   └── stacks/          # CDK stack definitions
-│       └── application-stack.ts  # Main application stack
-├── cdk.json            # CDK configuration
-├── tsconfig.json       # TypeScript configuration
-└── project.json       # Project configuration and build targets
-```
-
-### 2. Infra library code
-
-```
-common/constructs
-    └── src
-        └── core
-            └── cfn-guard.ts      # Provides a wrapper around @cdklabs/cdk-validator-cfnguard along with a suppressRule function
-            └── cfn-guard-rules
-                └── *.guard       # cfn guard ruleset definitions
-```
-
-Additionally, it:
-
-1. Configures build settings for CDK synthesis and deployment
-2. Installs required dependencies:
-   - aws-cdk-lib
-   - aws-cdk
-   - @cdklabs/cdk-validator-cfnguard
-   - constructs
-   - esbuild
-   - source-map-support
-   - tsx (dev dependency)
-
-## Features
-
-### 1. Cfn Guard integration
-
-The generated application includes Cfn guard integration which ensures security best practices via automated policy checks.
-
-```typescript
-import { CfnGuardValidator, RuleSet } from ':e2e-test/common-constructs';
-
-const app = new App({
-  policyValidationBeta1: [new CfnGuardValidator(RuleSet.AWS_PROTOTYPING)],
-});
-```
-
-### 2. Build and Deploy Targets
-
-The generator configures two main targets in your project.json:
-
-1. **Build Target**
-
-   - Synthesizes CDK templates
-   - Caches results for faster subsequent builds
-   - Outputs to `dist/<directory>/cdk.out`
-
-2. **Deploy Target**
-   - Deploys infrastructure to AWS
-   - Configures automatic approval for CI/CD pipelines
-   - Uses synthesized templates from the build target
-
-## Working with the Generated Application
-
-### Adding Resources
-
-Add AWS resources to your stack in `src/stacks/application-stack.ts`:
-
-```typescript
-import * as cdk from 'aws-cdk-lib';
-import { Construct } from 'constructs';
-/* Replace MyWebsite and MyApi with whatever you called them */
-import { UserIdentity, MyWebsite, MyApi } from ':my-org/common-constructs';
-
-export class ApplicationStack extends cdk.Stack {
-  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
-    super(scope, id, props);
-
-    const identity = new UserIdentity(this, 'UserIdentity');
-    const myapi = new MyApi(this, 'MyApi');
-    myapi.grantInvokeAccess(identity.identityPool.authenticatedRole);
-    new MyWebsite(this, 'Website');
-  }
-}
-```
-
-The generated code serves as a starting point that you can adapt to your specific infrastructure requirements while maintaining security best practices.
-
-### Building the Application
-
-To create a production build:
-
-```bash
-nx build my-infra
-```
-
-All built code is located in the `dist` folder at the root of your workspace. For example, if your infrastructure application is in `apps/infrastructure/my-infra`, the built code will be in `dist/apps/infrastructure/my-infra`. This includes:
-
-- Compiled TypeScript files
-- CDK synthesized templates in `dist/apps/infrastructure/my-infra/cdk.out`
-- Source maps for debugging
-
-### Deploying to AWS
-
-To deploy your infrastructure:
-
-```bash
-nx deploy my-infra --all
-```
-
-This command will deploy your infrastructure to AWS using the account and region configured in your AWS CLI.
-
-You can also perform a hotswap deployment if you are only making modifications to existing resources via the following command:
-
-```bash
-nx deploy my-infra --hotswap
-```
-
-### Cfn Guard Suppressions
-
-There may be instances where you want to suppress certain rules on resources. You can do this in two ways:
-
-#### Supress a rule on a given construct
-
-```typescript
-import { suppressRule } from ':my-org/common-constructs';
-
-...
-// suppresses the RULE_NAME for the given construct.
-suppressRule(construct, 'RULE_NAME');
-```
-
-#### Supress a rule on a descendant construct
-
-```typescript
-import { suppressRule } from ':my-org/common-constructs';
-
-...
-// Supresses the RULE_NAME for the construct or any of its descendants if it is an instance of Bucket
-suppressRule(construct, 'RULE_NAME', (construct) => construct instanceof Bucket);
-```