@aws/nx-plugin 0.0.0

package/README.md

@@ -0,0 +1,63 @@
+# PACE Plugin for Nx
+
+This plugin provides a collection of generators to help you build cloud-native applications with AWS, TypeScript, and React.
+
+## What are Generators?
+
+Generators (also known as schematics) are powerful tools that automate the creation and modification of code. They help maintain consistency across your codebase by following established patterns and best practices. When you run a generator, it:
+
+1. Prompts for necessary configuration options
+2. Creates new files from templates
+3. Updates existing files when needed
+4. Follows project conventions automatically
+
+For more information about generators, see the [Nx Generator documentation](https://nx.dev/plugin-features/use-code-generators).
+
+## Getting started
+
+### Install the plugin
+
+From the root of your workspace run:
+
+```bash
+nx add @aws/nx-plugin
+```
+
+### IDE Setup
+
+For the best development experience, install the Nx Console extension for your IDE:
+
+- VS Code: [Nx Console for VS Code](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
+- JetBrains IDEs: [Nx Console for JetBrains](https://plugins.jetbrains.com/plugin/21060-nx-console)
+
+The Nx Console provides:
+- Interactive generator configuration
+- Command autocompletion
+- Visual project graph
+- Integrated task runner
+
+### Using Generators
+
+Refer to the individual generator README.md files below for detailed installation instructions.
+
+## Available Generators
+
+### Cloudscape Website
+
+- [Cloudscape Website App](src/cloudscape-website/app/README.md) - Generate a new Cloudscape-based web application
+- [Cognito Authentication](src/cloudscape-website/cognito-auth/README.md) - Add AWS Cognito authentication to your Cloudscape website
+- [Runtime Configuration](src/cloudscape-website/runtime-config/README.md) - Add runtime configuration capabilities to your Cloudscape website
+
+### Infrastructure
+
+- [Infrastructure App](src/infra/app/README.md) - Generate AWS CDK infrastructure code for your application
+
+### tRPC
+
+- [tRPC Backend](src/trpc/backend/README.md) - Generate a tRPC backend service with AWS Lambda integration
+- [tRPC React](src/trpc/react/README.md) - Add tRPC client integration to your React application
+
+### TypeScript
+
+- [TypeScript Library](src/ts/lib/README.md) - Generate a new TypeScript library with best practices and testing setup
+- [CJS to ESM](src/ts/cjs-to-esm/README.md) - Convert CommonJS modules to ECMAScript modules

package/generators.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "pace",
+  "version": "0.0.1",
+  "generators": {
+    "ts#lib": {
+      "factory": "./src/ts/lib/generator",
+      "schema": "./src/ts/lib/schema.json",
+      "description": "Generates a TypeScript library"
+    },
+    "ts#cjs-to-esm": {
+      "factory": "./src/ts/cjs-to-esm/generator",
+      "schema": "./src/ts/cjs-to-esm/schema.json",
+      "description": "Convert CommonJS TypeScript/JavaScript files to ESM"
+    },
+    "cloudscape-website#app": {
+      "factory": "./src/cloudscape-website/app/generator",
+      "schema": "./src/cloudscape-website/app/schema.json",
+      "description": "Generates a React static website based on Cloudscape"
+    },
+    "cloudscape-website#cognito-auth": {
+      "factory": "./src/cloudscape-website/cognito-auth/generator",
+      "schema": "./src/cloudscape-website/cognito-auth/schema.json",
+      "description": "Adds cognito auth to an existing cloudscape website"
+    },
+    "cloudscape-website#runtime-config": {
+      "factory": "./src/cloudscape-website/runtime-config/generator",
+      "schema": "./src/cloudscape-website/runtime-config/schema.json",
+      "description": "Adds runtime config to an existing cloudscape website"
+    },
+    "infra#app": {
+      "factory": "./src/infra/app/generator",
+      "schema": "./src/infra/app/schema.json",
+      "description": "Generates a cdk application"
+    },
+    "trpc#backend": {
+      "factory": "./src/trpc/backend/generator",
+      "schema": "./src/trpc/backend/schema.json",
+      "description": "creates a trpc backend"
+    },
+    "trpc#react": {
+      "factory": "./src/trpc/react/generator",
+      "schema": "./src/trpc/react/schema.json",
+      "description": "provides React integration to a React website"
+    },
+    "gitlab": {
+      "factory": "./src/gitlab/generator",
+      "schema": "./src/gitlab/schema.json",
+      "description": "Gitlab CI/CD pipeline"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aws/nx-plugin",
+  "version": "0.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "generators": "./generators.json",
+  "dependencies": {
+    "@nx/eslint": "20.0.10",
+    "@nx/js": "20.0.10",
+    "@nx/react": "20.0.10",
+    "@phenomnomnominal/tsquery": "6.1.3",
+    "lodash.kebabcase": "4.1.1",
+    "typescript": "~5.5.4",
+    "vitest": "^1.6.0",
+    "minimatch": "^10.0.1",
+    "vite": "^5.4.0",
+    "@nx/vite": "20.0.10",
+    "@nx/devkit": "20.1.1",
+    "nx": "19.8.2"
+  },
+  "types": "./src/index.d.ts"
+}

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

@@ -0,0 +1,253 @@
+# 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 "cloudscape-website#app"
+4. Fill in the required parameters in the form
+5. Click "Run"
+
+### 2. Using CLI
+
+Generate the application:
+```bash
+nx g @aws/nx-plugin:cloudscape-website#app 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:cloudscape-website#app 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/
+│   ├── <name>/           # Infrastructure specific to this website
+│   │   └── index.ts      # Website infrastructure stack
+│   │   └── static-website.ts # Contains the StaticWebsite construct
+│   │   └── cloudfront-web-acl.ts # Sets up the ACL
+│   │   └── webacl_event_handler # Custom resource to support cross region ACL deployment
+│   └── index.ts          # Exports for all constructs
+├── tsconfig.json         # TypeScript configuration
+└── project.json         # Project configuration and build targets
+```
+
+Additionally, it:
+1. Configures build settings for production deployment
+2. Installs required dependencies:
+   - @aws-northstar/ui
+   - @cloudscape-design/components
+   - @cloudscape-design/board-components
+   - react-router-dom
+   - aws-cdk-lib
+   - constructs
+   - cdk-nag
+
+## Infrastructure Architecture
+
+```mermaid
+graph TD
+    subgraph AWS Cloud
+        CF[CloudFront Distribution] --> S3[S3 Bucket]
+        CF --> WAF[WAF Rules]
+        OAC[Origin Access Control] --> S3
+    end
+```
+
+The infrastructure stack 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)**
+   - Web exploit protection
+   - Rate limiting
+   - IP-based filtering
+
+4. **Origin Access Control**
+   - Secure S3 bucket access
+   - Restricted to CloudFront only
+
+## Using the StaticWebsite Construct
+
+After generating the application, you can use the generated `StaticWebsite` construct in your CDK code:
+
+```typescript
+import { App, Stack } from 'aws-cdk-lib';
+import { StaticWebsite } from ':my-org/common-constructs';
+
+export class MyWebsiteStack extends Stack {
+  constructor(scope: App, id: string) {
+    super(scope, id);
+
+    // Create the static website with the pre-configured setup
+    new StaticWebsite(this, 'MyWebsite');
+  }
+}
+```
+
+The StaticWebsite construct is pre-configured with:
+- S3 bucket for hosting website content
+- CloudFront distribution with Origin Access Control
+- WAF rules for security
+- 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. You can modify:
+- `static-website.ts` to adjust the CloudFront distribution settings or S3 bucket configuration
+- `cloudfront-web-acl.ts` to customize WAF rules and rate limiting
+- `webacl_event_handler` to modify the cross-region WAF deployment behavior
+
+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
+    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 { useContext } from 'react';
+import { RuntimeConfigContext } from './components/RuntimeConfig';
+
+const MyComponent = () => {
+  const runtimeConfig = useContext(RuntimeConfigContext);
+
+  return (
+    <div>
+      <p>API Endpoint: {runtimeConfig?.myFeature?.apiEndpoint}</p>
+      <p>Region: {runtimeConfig?.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>
+    <BrowserRouter>
+      {/* Your app components */}
+    </BrowserRouter>
+  </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