From c3c2a0ecf11e971726cf2f2dfad04234b51b1d9f Mon Sep 17 00:00:00 2001 From: Matthew Warman Date: Tue, 10 Feb 2026 11:38:36 -0500 Subject: [PATCH 1/4] Add comprehensive configuration guide for React Starter application and AWS CDK --- docs/CONFIGURATION_GUIDE.md | 434 ++++++++++++++++++++++++++++++++++++ 1 file changed, 434 insertions(+) create mode 100644 docs/CONFIGURATION_GUIDE.md diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md new file mode 100644 index 0000000..792eb39 --- /dev/null +++ b/docs/CONFIGURATION_GUIDE.md @@ -0,0 +1,434 @@ +# Configuration Guide + +This guide provides comprehensive information about configuring the React Starter application and its AWS CDK infrastructure. + +## Application Configuration + +The React application configuration is managed through environment variables prefixed with `VITE_`. These variables are available at build time and runtime in your React components. + +### Environment Variables + +The following environment variables are available for configuring the React application: + +| Variable | Type | Description | Default | Required | +| --------------------------------- | ------ | ---------------------------------------------------- | ------- | -------- | +| `VITE_BASE_URL_API` | string | Base URL for API requests | - | Yes | +| `VITE_TOAST_AUTO_DISMISS_MILLIS` | number | Auto-dismiss duration for toast notifications (ms) | `5000` | No | +| `VITE_BUILD_DATE` | string | Build date (YYYY-MM-DD format) | - | No | +| `VITE_BUILD_TIME` | string | Build time (HH:MM:SS format) | - | No | +| `VITE_BUILD_TS` | string | Build timestamp (ISO 8601 format) | - | No | +| `VITE_BUILD_COMMIT_SHA` | string | Git commit SHA of the build | - | No | +| `VITE_BUILD_ENV_CODE` | string | Environment code (e.g., `local`, `dev`, `qa`, `prd`) | - | No | +| `VITE_BUILD_WORKFLOW_NAME` | string | CI/CD workflow name | - | No | +| `VITE_BUILD_WORKFLOW_RUN_NUMBER` | string | CI/CD workflow run number | - | No | +| `VITE_BUILD_WORKFLOW_RUN_ATTEMPT` | string | CI/CD workflow run attempt number | - | No | + +### Setup + +1. **Copy the example configuration file:** + + ```bash + cp .env.example .env + ``` + +2. **Update variables for your environment:** + + ```env + VITE_BASE_URL_API=https://your-api.example.com + VITE_TOAST_AUTO_DISMISS_MILLIS=5000 + ``` + +3. **Build information** (typically set by CI/CD pipeline): + ```env + VITE_BUILD_DATE=2026-02-10 + VITE_BUILD_TIME=14:30:00 + VITE_BUILD_TS=2026-02-10T14:30:00+0000 + VITE_BUILD_COMMIT_SHA=abc123def456 + VITE_BUILD_ENV_CODE=dev + VITE_BUILD_WORKFLOW_NAME=Build + VITE_BUILD_WORKFLOW_RUN_NUMBER=42 + VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 + ``` + +### Accessing Configuration + +Application configuration values are accessible directly in your React components since Vite automatically injects them: + +```typescript +// API base URL +const apiUrl = import.meta.env.VITE_BASE_URL_API; + +// Toast settings +const toastDuration = import.meta.env.VITE_TOAST_AUTO_DISMISS_MILLIS; + +// Build information +const buildDate = import.meta.env.VITE_BUILD_DATE; +const buildCommit = import.meta.env.VITE_BUILD_COMMIT_SHA; +``` + +### Local Development + +For local development, create a `.env` file in the root directory with local values: + +```env +VITE_BASE_URL_API=http://localhost:3000 +VITE_TOAST_AUTO_DISMISS_MILLIS=5000 +VITE_BUILD_DATE=1970-01-01 +VITE_BUILD_TIME=00:00:00 +VITE_BUILD_TS=1970-01-01T00:00:00+0000 +VITE_BUILD_COMMIT_SHA=local +VITE_BUILD_ENV_CODE=local +VITE_BUILD_WORKFLOW_NAME=local +VITE_BUILD_WORKFLOW_RUN_NUMBER=1 +VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 +``` + +--- + +## Infrastructure Configuration + +The infrastructure configuration is managed through environment variables prefixed with `CDK_`. These variables control how AWS resources are provisioned and deployed using the AWS CDK. + +### Environment Variables + +The following environment variables are available for configuring the infrastructure: + +| Variable | Type | Description | Default | Required | +| -------------------------------- | ------ | ----------------------------------------------------------------------------- | -------------------------- | -------- | +| `CDK_APP_NAME` | string | Application name used in resource naming and tagging | `react-starter` | No | +| `CDK_ENV` | enum | Deployment environment: `dev`, `qa`, `prd` | - | Yes | +| `CDK_ACCOUNT` | string | AWS account ID for deployment | Auto-detected from AWS CLI | No | +| `CDK_REGION` | string | AWS region for deployment (e.g., `us-east-1`) | Auto-detected from AWS CLI | No | +| `CDK_OU` | string | Organizational Unit for resource tagging | `unknown` | No | +| `CDK_OWNER` | string | Owner tag for resource tracking | `unknown` | No | +| `CDK_ASSET_PATH` | string | Path to application build artifacts (relative to infrastructure directory) | `../dist` | No | +| `CDK_DOMAIN_NAME` | string | Custom domain name for the application CDN (e.g., `app.example.com`) | - | No | +| `CDK_CERTIFICATE_ARN` | string | ACM certificate ARN for custom domain (must be in `us-east-1` for CloudFront) | - | No | +| `CDK_HOSTED_ZONE_ID` | string | Route53 hosted zone ID for DNS records | - | No | +| `CDK_HOSTED_ZONE_NAME` | string | Route53 hosted zone name (e.g., `example.com`) | - | No | +| `CDK_STORYBOOK_ASSET_PATH` | string | Path to Storybook build artifacts (relative to infrastructure directory) | `../storybook-static` | No | +| `CDK_STORYBOOK_DOMAIN_NAME` | string | Custom domain name for Storybook CDN | - | No | +| `CDK_STORYBOOK_CERTIFICATE_ARN` | string | ACM certificate ARN for Storybook custom domain | - | No | +| `CDK_STORYBOOK_HOSTED_ZONE_ID` | string | Route53 hosted zone ID for Storybook DNS records | - | No | +| `CDK_STORYBOOK_HOSTED_ZONE_NAME` | string | Route53 hosted zone name for Storybook | - | No | + +### Setup + +1. **Navigate to the infrastructure directory:** + + ```bash + cd infrastructure + ``` + +2. **Copy the example configuration file:** + + ```bash + cp .env.example .env + ``` + +3. **Update variables for your environment:** + ```env + CDK_ENV=dev + CDK_APP_NAME=react-starter + CDK_ACCOUNT=123456789012 + CDK_REGION=us-east-1 + CDK_OU=software-engineering + CDK_OWNER=your-team + ``` + +### Usage + +Infrastructure configuration is loaded and validated through the `getConfig()` function in `infrastructure/utils/config.ts`: + +```typescript +import { getConfig, getTags, getEnvironmentConfig } from './utils/config'; + +const config = getConfig(); +const tags = getTags(config); +const envConfig = getEnvironmentConfig(config); + +console.log(`Environment: ${config.CDK_ENV}`); +console.log(`App name: ${config.CDK_APP_NAME}`); +console.log(`Tags:`, tags); +``` + +### Configuration Files + +Infrastructure configuration can be provided through: + +1. **Environment variables** - Set directly in your shell or CI/CD pipeline (highest priority) +2. **.env file** - Create a `.env` file in the `infrastructure/` directory for local development +3. **Default values** - Specified in the Zod schema (lowest priority) + +### Resource Tagging + +All AWS resources created by the CDK are automatically tagged with the following tags: + +| Tag | Description | Source | +| ------- | -------------------------------- | -------------- | +| `App` | Application name | `CDK_APP_NAME` | +| `Env` | Environment (`dev`, `qa`, `prd`) | `CDK_ENV` | +| `OU` | Organizational Unit | `CDK_OU` | +| `Owner` | Team or individual responsible | `CDK_OWNER` | + +These tags are used for cost allocation, resource management, and identifying resources in AWS. + +### Example Configurations + +#### Development Environment + +Create `infrastructure/.env` for development deployment: + +```env +############################################### +## Development Environment Configuration +############################################### + +CDK_APP_NAME=react-starter +CDK_ENV=dev +CDK_ACCOUNT=123456789012 +CDK_REGION=us-east-1 + +### Resource Tagging ### +CDK_OU=software-engineering +CDK_OWNER=frontend-team + +### CDN Configuration ### +CDK_ASSET_PATH=../dist +CDK_DOMAIN_NAME=react-starter.dev.example.com +CDK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_HOSTED_ZONE_NAME=dev.example.com + +### Storybook CDN Configuration ### +CDK_STORYBOOK_ASSET_PATH=../storybook-static +CDK_STORYBOOK_DOMAIN_NAME=react-starter-storybook.dev.example.com +CDK_STORYBOOK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_STORYBOOK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_STORYBOOK_HOSTED_ZONE_NAME=dev.example.com +``` + +#### QA Environment + +```env +############################################### +## QA Environment Configuration +############################################### + +CDK_APP_NAME=react-starter +CDK_ENV=qa +CDK_ACCOUNT=123456789012 +CDK_REGION=us-east-1 + +CDK_OU=software-engineering +CDK_OWNER=frontend-team + +CDK_ASSET_PATH=../dist +CDK_DOMAIN_NAME=react-starter.qa.example.com +CDK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_HOSTED_ZONE_NAME=qa.example.com + +CDK_STORYBOOK_ASSET_PATH=../storybook-static +CDK_STORYBOOK_DOMAIN_NAME=react-starter-storybook.qa.example.com +CDK_STORYBOOK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_STORYBOOK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_STORYBOOK_HOSTED_ZONE_NAME=qa.example.com +``` + +#### Production Environment + +```env +############################################### +## Production Environment Configuration +############################################### + +CDK_APP_NAME=react-starter +CDK_ENV=prd +CDK_ACCOUNT=123456789012 +CDK_REGION=us-east-1 + +CDK_OU=software-engineering +CDK_OWNER=frontend-team + +CDK_ASSET_PATH=../dist +CDK_DOMAIN_NAME=react-starter.example.com +CDK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_HOSTED_ZONE_NAME=example.com + +CDK_STORYBOOK_ASSET_PATH=../storybook-static +CDK_STORYBOOK_DOMAIN_NAME=react-starter-storybook.example.com +CDK_STORYBOOK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +CDK_STORYBOOK_HOSTED_ZONE_ID=Z1234567890ABC +CDK_STORYBOOK_HOSTED_ZONE_NAME=example.com +``` + +### AWS Account and Region + +The CDK uses the following precedence for account and region: + +1. **Explicit CDK variables** (highest priority) + - `CDK_ACCOUNT` - AWS account ID + - `CDK_REGION` - AWS region + +2. **AWS CDK environment defaults** + - `CDK_DEFAULT_ACCOUNT` - Auto-detected from AWS credentials + - `CDK_DEFAULT_REGION` - Auto-detected from AWS profile + +3. **AWS CLI configuration** + - Uses the configured AWS profile and region + +If neither explicit CDK variables nor CDK_DEFAULT environment variables are set, the CDK will fail with an error requesting explicit account and region configuration. + +### Custom Domain and SSL/TLS + +To use a custom domain for your application: + +1. **Create an ACM certificate** in `us-east-1` (required for CloudFront): + + ```bash + aws acm request-certificate \ + --domain-name react-starter.example.com \ + --region us-east-1 + ``` + +2. **Verify the certificate** in the ACM console + +3. **Configure in `.env`:** + + ```env + CDK_DOMAIN_NAME=react-starter.example.com + CDK_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxxxx + CDK_HOSTED_ZONE_ID=Z1234567890ABC + CDK_HOSTED_ZONE_NAME=example.com + ``` + +4. **Deploy** the CDK stack + +--- + +## Configuration Validation + +Both application and infrastructure configurations are validated at runtime: + +- **Application**: Environment variables are available in Vite at build time +- **Infrastructure**: Configuration is validated using Zod schema when `getConfig()` is called + +If validation fails, you'll see detailed error messages indicating which variables are missing or invalid. + +### Common Validation Errors + +``` +CDK_ENV must be one of: dev, qa, prd +``` + +Ensure `CDK_ENV` is set to one of the allowed values. + +``` +CDK configuration validation failed: CDK_ASSET_PATH: Invalid type. Expected string +``` + +Ensure all required configuration variables are set as the correct type. + +--- + +## Environment-Specific Recommendations + +### Development + +- Use auto-detected AWS account and region from AWS CLI +- Deploy to a development AWS account +- Enable detailed logging in your application +- Use minimal resource sizes +- Consider using S3 + CloudFront for cost-effective hosting + +### QA + +- Use dedicated QA AWS account +- Configure proper domain names for testing +- Use production-like configurations +- Enable monitoring and alerting + +### Production + +- Use dedicated production AWS account +- Configure custom domains with SSL/TLS certificates +- Use appropriate resource sizes +- Enable comprehensive monitoring, logging, and alerting +- Implement backup and disaster recovery plans +- Consider using CloudFront with WAF for protection + +--- + +## Troubleshooting + +### CDK Deployment Fails with "Account/Region" Error + +**Problem**: CDK deployment fails with an error about missing account or region. + +**Solution**: + +1. Set `CDK_ACCOUNT` and `CDK_REGION` explicitly in `.env` +2. Ensure AWS CLI is configured with `aws configure` +3. Verify with: `aws sts get-caller-identity` + +### Application Build Variables Not Available + +**Problem**: `import.meta.env.VITE_*` variables are undefined at runtime. + +**Solution**: + +1. Ensure variables in `.env` are prefixed with `VITE_` +2. Restart the development server after changing `.env` +3. Verify with: `echo $VITE_BASE_URL_API` + +### CDK Configuration Validation Errors + +**Problem**: CDK fails to load configuration with validation errors. + +**Solution**: + +1. Check `.env` file syntax (no quotes around values unless necessary) +2. Verify required variables are set +3. Check for typos in variable names +4. Ensure enum values match allowed options + +### AWS Credentials Issues + +**Problem**: CDK cannot access AWS account. + +**Solution**: + +1. Configure AWS credentials: `aws configure` +2. Verify access: `aws sts get-caller-identity` +3. Use AWS SSO if available: `aws sso login --profile YOUR_PROFILE` +4. Ensure IAM user/role has CDK permissions + +--- + +## Best Practices + +1. **Never commit `.env` files** - Use `.gitignore` to exclude them +2. **Use environment-specific `.env` files** - Keep configurations separate per environment +3. **Document configuration changes** - Update this guide when adding new variables +4. **Validate early** - Run CDK synthesis before deployment: `cdk synth` +5. **Use AWS CDK best practices**: + - Always tag resources for cost allocation + - Use stack outputs for important values + - Implement proper error handling + - Test in lower environments first +6. **Secure sensitive data**: + - Use AWS Secrets Manager for secrets + - Never commit credentials to version control + - Use IAM roles instead of access keys when possible +7. **Monitor and log**: + - Enable CloudWatch logging for CDN and application + - Set up CloudWatch alarms for critical metrics + - Review logs regularly for issues + +
+ +--- + +For more information about this project, see the main [README](../README.md) or visit the [documentation](./README.md). From 9d2d48ff2d84e92ddafdc3405cd3339a2e43caed Mon Sep 17 00:00:00 2001 From: Matthew Warman Date: Tue, 10 Feb 2026 11:39:35 -0500 Subject: [PATCH 2/4] Add link to Configuration Guide in README --- docs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.md b/docs/README.md index 3093b25..833628d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ Welcome to the project documentation for the React Starter project. This directo ## Table of Contents - [DevOps Guide](./DEVOPS_GUIDE.md): GitHub Actions workflows, CI/CD, and automation. +- [Configuration Guide](./CONFIGURATION_GUIDE.md): Application and infrastructure configuration, environment variables, and validation. - [Infrastructure Guide](./INFRASTRUCTURE_GUIDE.md): AWS CDK Infrastructure as Code.
From 21c58cd7d82434134ba89d70c7be09e2823e45ef Mon Sep 17 00:00:00 2001 From: Matthew Warman Date: Tue, 10 Feb 2026 11:44:26 -0500 Subject: [PATCH 3/4] Add unit testing configuration and notes to Configuration Guide --- docs/CONFIGURATION_GUIDE.md | 59 +++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md index 792eb39..f67a1d5 100644 --- a/docs/CONFIGURATION_GUIDE.md +++ b/docs/CONFIGURATION_GUIDE.md @@ -83,6 +83,65 @@ VITE_BUILD_WORKFLOW_RUN_NUMBER=1 VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 ``` +### Unit Testing + +For running unit tests, create a `.env.test.local` file in the root directory with values optimized for the test environment. This configuration is used by Vitest when running unit tests. + +1. **Copy the example configuration file:** + + ```bash + cp .env.example .env.test.local + ``` + +2. **Update with test-specific values:** + + ```env + # Provided by Pipeline (Simulated) + VITE_BUILD_DATE=1970-01-01 + VITE_BUILD_TIME=00:00:00 + VITE_BUILD_TS=1970-01-01T00:00:00+0000 + VITE_BUILD_COMMIT_SHA=test + VITE_BUILD_ENV_CODE=test + VITE_BUILD_WORKFLOW_NAME=test + VITE_BUILD_WORKFLOW_RUN_NUMBER=1 + VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 + + # API Configuration + # Use JSONPlaceholder for mock API testing + VITE_BASE_URL_API=https://jsonplaceholder.typicode.com + + # Toasts Configuration + # Use shorter duration in tests for faster test execution + VITE_TOAST_AUTO_DISMISS_MILLIS=1500 + ``` + +#### Test Configuration Notes + +- **API Base URL**: Uses [JSONPlaceholder](https://jsonplaceholder.typicode.com/) - a free fake REST API for testing. In actual test environments, API calls are typically mocked using MSW (Mock Service Worker). +- **Toast Duration**: Reduced to 1500ms for faster test execution while still allowing time for async operations. +- **Build Information**: All build-related variables are set to static test values, ensuring consistent snapshots and reproducible test results. +- **Environment Code**: Set to `test` to distinguish test runs from development and production. + +#### Usage with MSW + +The test configuration works seamlessly with [MSW](https://mswjs.io/) (Mock Service Worker), which intercepts HTTP requests in tests. The `VITE_BASE_URL_API` can point to a test server, and MSW handlers will intercept and mock responses: + +```typescript +// Example MSW handler in tests +import { http, HttpResponse } from 'msw'; +import { setupServer } from 'msw/node'; + +const server = setupServer( + http.get('https://jsonplaceholder.typicode.com/users', () => { + return HttpResponse.json([{ id: 1, name: 'Test User' }]); + }), +); + +beforeAll(() => server.listen()); +afterEach(() => server.resetHandlers()); +afterAll(() => server.close()); +``` + --- ## Infrastructure Configuration From 2711dc02e5915ba657d35e86fc34ff1dae791bda Mon Sep 17 00:00:00 2001 From: Matthew Warman Date: Tue, 10 Feb 2026 11:47:51 -0500 Subject: [PATCH 4/4] Update README to reference Configuration Guide for application setup --- README.md | 54 +----------------------------------------------------- 1 file changed, 1 insertion(+), 53 deletions(-) diff --git a/README.md b/README.md index 62cef07..d3566b0 100644 --- a/README.md +++ b/README.md @@ -151,59 +151,7 @@ The _Tailwind CSS IntelliSense_ extension is a must-have companion in all projec ## Configuration -The application is configured using Environment Variables. Because single-page applications are static, environment variable values are injected into the application during the build. The environment variables may be sourced from the environment or `.env` files as described in the [Vite documentation](https://vitejs.dev/guide/env-and-mode.html). - -### `.env` files - -> **NOTE:** Because they may contain sensitive information, `.env` files are not committed to the repository. - -After project installation and before running the application locally, create the following `.env` files in the project base directory. Copy the `.env.example` file to get started. Learn more in the official [Vite guide for environment variables and modes](https://vitejs.dev/guide/env-and-mode.html). - -#### `.env.local` - -The `.env.local` configuration file provides the configuration values when the application is started on a developer's local machine. - -``` -# Provided by Pipeline (Simulated) -VITE_BUILD_DATE=1970-01-01 -VITE_BUILD_TIME=00:00:00 -VITE_BUILD_TS=1970-01-01T00:00:00+0000 -VITE_BUILD_COMMIT_SHA=local -VITE_BUILD_ENV_CODE=local -VITE_BUILD_WORKFLOW_NAME=local -VITE_BUILD_WORKFLOW_RUN_NUMBER=1 -VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 - -# API Configuration -VITE_BASE_URL_API=https://jsonplaceholder.typicode.com - -# Toasts Configuration -VITE_TOAST_AUTO_DISMISS_MILLIS=5000 -``` - -#### `.env.test.local` - -The `.env.test.local` configuration file provides configuration values used when unit tests are executed on a developer's local machine. - -> **NOTE:** Use the same values when running tests in a CI/CD pipeline. - -``` -# Provided by Pipeline (Simulated) -VITE_BUILD_DATE=1970-01-01 -VITE_BUILD_TIME=00:00:00 -VITE_BUILD_TS=1970-01-01T00:00:00+0000 -VITE_BUILD_COMMIT_SHA=test -VITE_BUILD_ENV_CODE=test -VITE_BUILD_WORKFLOW_NAME=test -VITE_BUILD_WORKFLOW_RUN_NUMBER=1 -VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1 - -# API Configuration -VITE_BASE_URL_API=https://jsonplaceholder.typicode.com - -# Toasts Configuration -VITE_TOAST_AUTO_DISMISS_MILLIS=1500 -``` +See the [Configuration Guide](./docs/CONFIGURATION_GUIDE.md) in the [project docs](./docs/README.md) for detailed information about application and infrastructure configuration. ## Available Scripts