docs: clarify that domainName is optional with auto-generated defaults

cdk/bin/cdk.ts

@@ -13,7 +13,9 @@ interface EnvironmentProps {
    * Custom domain name for the webapp and Cognito.
    * You need to have a public Route53 hosted zone for the domain name in your AWS account.
    *
-   * @default No custom domain name.
+   * @default No custom domain name. When not specified, the stack automatically generates
+   * a random prefix for the Cognito domain (e.g., webapp-abc123def4.auth.us-west-2.amazoncognito.com)
+   * and uses the CloudFront default domain (e.g., d1234567890.cloudfront.net) for the webapp.
    */
   domainName?: string;
 

cdk/lib/constructs/auth/index.ts

@@ -10,7 +10,17 @@ import { readFileSync } from 'fs';
 import { join } from 'path';
 
 export interface AuthProps {
+  /**
+   * Route 53 hosted zone for custom domain.
+   *
+   * @default No custom domain. A random prefix will be automatically generated for the Cognito domain.
+   */
   readonly hostedZone?: IHostedZone;
+  /**
+   * ACM certificate for custom domain (must be in us-east-1 for Cognito).
+   *
+   * @default No custom domain.
+   */
   readonly sharedCertificate?: ICertificate;
 }
 
@@ -29,6 +39,7 @@ export class Auth extends Construct {
     if (!hostedZone) {
       // When we do not use a custom domain, we must make domainPrefix unique in the AWS region.
       // To avoid a collision, we generate a random string with CFn custom resource.
+      // This allows the stack to work without requiring a custom domain setup.
       const generator = new SingletonFunction(this, 'RandomStringGenerator', {
         runtime: Runtime.NODEJS_22_X,
         handler: 'index.handler',

cdk/lib/constructs/cf-lambda-furl-service/service.ts

@@ -23,6 +23,8 @@ import { AwsCustomResource, PhysicalResourceId, AwsCustomResourcePolicy } from '
 
 export interface CloudFrontLambdaFunctionUrlServiceProps {
   /**
+   * Subdomain name for the service. If not specified, the root domain will be used.
+   *
    * @default use root domain
    */
   subDomain?: string;
@@ -39,7 +41,17 @@ export interface CloudFrontLambdaFunctionUrlServiceProps {
   basicAuthUsername?: string;
   basicAuthPassword?: string;
 
+  /**
+   * Route 53 hosted zone for custom domain.
+   *
+   * @default No custom domain. CloudFront's default domain will be used.
+   */
   hostedZone?: IHostedZone;
+  /**
+   * ACM certificate for custom domain (must be in us-east-1 for CloudFront).
+   *
+   * @default No custom domain.
+   */
   certificate?: ICertificate;
   signPayloadHandler: EdgeFunction;
   accessLogBucket: Bucket;

cdk/lib/constructs/webapp.ts

@@ -26,10 +26,22 @@ export interface WebappProps {
   eventBus: EventBus;
   asyncJob: AsyncJob;
 
+  /**
+   * Route 53 hosted zone for custom domain.
+   *
+   * @default No custom domain. The webapp will use CloudFront's default domain (e.g., d1234567890.cloudfront.net).
+   */
   hostedZone?: IHostedZone;
+  /**
+   * ACM certificate for custom domain (must be in us-east-1 for CloudFront).
+   *
+   * @default No custom domain.
+   */
   certificate?: ICertificate;
   /**
-   * Use root domain
+   * Subdomain name for the webapp. If not specified, the root domain will be used.
+   *
+   * @default Use root domain
    */
   subDomain?: string;
 }

cdk/lib/main-stack.ts

@@ -14,10 +14,22 @@ import { EventBus } from './constructs/event-bus/';
 interface MainStackProps extends StackProps {
   readonly signPayloadHandler: EdgeFunction;
 
+  /**
+   * Custom domain name for the webapp and Cognito.
+   *
+   * @default No custom domain. CloudFront and Cognito will use their default domains.
+   */
   readonly domainName?: string;
+  /**
+   * ACM certificate for custom domain (must be in us-east-1).
+   *
+   * @default No custom domain.
+   */
   readonly sharedCertificate?: ICertificate;
 
   /**
+   * Use a NAT instance instead of NAT Gateways for cost optimization.
+   *
    * @default true
    */
   readonly useNatInstance?: boolean;

cdk/lib/us-east-1-stack.ts

@@ -6,6 +6,11 @@ import { EdgeFunction } from './constructs/cf-lambda-furl-service/edge-function'
 import { join } from 'path';
 
 interface UsEast1StackProps extends cdk.StackProps {
+  /**
+   * Custom domain name for the webapp and Cognito.
+   *
+   * @default No custom domain. CloudFront and Cognito will use their default domains.
+   */
   domainName?: string;
 }