cdk-nextjs-standalone

The Nextjs construct automates the deployment of Next.js applications to AWS by orchestrating several specialized sub-constructs. The flow follows a specific order to ensure that environment variable placeholders are correctly resolved before assets are served.

1. Build Phase (NextjsBuild): Runs npx open-next build in your repository. This generates the .next folder and uses open-next to create handler code for the server, image optimization, revalidation, and warmer functions.
   • Environment Variables: It injects process environment variables, NextjsProps.environment, and Nextjs.nodeEnv.
   • Token Handling: Unresolved CDK tokens (e.g., ${TOKEN[Bucket.Name.1234]}) are replaced with placeholders like {{ BUCKET_NAME }} to be resolved later by a CloudFormation Custom Resource.
2. Static Assets Phase (NextjsStaticAssets): Creates an S3 bucket and deploys static assets.
   • Placeholder Substitution: Uses a NextjsBucketDeployment (a CloudFormation Custom Resource) to download assets from the CDK Assets bucket, replace placeholders with resolved values, and upload them to the target bucket.
   • Security: Only NEXT_PUBLIC environment variable placeholders are passed to substitutionConfig; private server variables are not included in static assets.
3. Server Phase (NextjsServer): Deploys the Next.js server code via Lambda.
   • Token Handling: Replaces all (public and private) unresolved tokens within the open-next generated server function code.
   • ISR Support: Automatically adds CACHE_BUCKET_NAME, CACHE_BUCKET_KEY, and CACHE_BUCKET_REGION to support Incremental Static Regeneration.
   • Bundling: Uses esbuild to bundle the Lambda code.
4. Optimization & Revalidation (NextjsImage & NextjsRevalidation): Deploys Lambda functions using the bundled code from open-next to handle image optimization and revalidation.
5. Cache Invalidation (NextjsInvalidation): Invalidates the CloudFront Distribution. This step explicitly depends on the completion of NextjsStaticAssets, NextjsServer, and NextjsImage to ensure the cache is only cleared once new assets are fully deployed.

To deploy a NextJS application using AWS CDK, use the Nextjs construct from cdk-nextjs-standalone. This construct requires the nextjsPath option, which is the relative path from your project root to your NextJS application directory. The deployment uses NextJS's standalone output mode to provide SSR, API support, and static file hosting via CloudFront and S3.

import { App, Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Nextjs } from 'cdk-nextjs-standalone';

class WebStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    const nextjs = new Nextjs(this, 'Nextjs', {
      nextjsPath: './web', // relative path from your project root to NextJS
    });
    new CfnOutput(this, 'CloudFrontDistributionDomain', {
      value: nextjs.distribution.distributionDomain,
    });
  }
}

const app = new App();
new WebStack(app, 'web');

When using OptionalCustomResourceProps, you can provide a serviceToken using several methods:

1. CDK Provider Framework (Recommended)

Use the aws-cdk/custom-resources module to create a robust provider.

const provider = new customresources.Provider(this, 'ResourceProvider', {
  onEventHandler,
  isCompleteHandler, // optional
});

new CustomResource(this, 'MyResource', {
  serviceToken: provider.serviceToken,
});

2. AWS Lambda Function

Directly use a Lambda function ARN (not recommended to use raw Lambda functions directly).

new CustomResource(this, 'MyResource', {
  serviceToken: myFunction.functionArn,
});

3. SNS Topic

Publish lifecycle events to an SNS topic (not recommended to use raw SNS topics directly).

new CustomResource(this, 'MyResource', {
  serviceToken: myTopic.topicArn,
});

// Example using the CDK Provider framework
import * as customresources from 'aws-cdk-lib/custom-resources';
import { CustomResource } from 'aws-cdk-lib';

const provider = new customresources.Provider(this, 'ResourceProvider', {
  onEventHandler: myHandler,
});

new CustomResource(this, 'MyResource', {
  serviceToken: provider.serviceToken,
});

When using OptionalEdgeFunctionProps, you can control how logs are handled.

Recommended Approach: Instead of using deprecated properties like logRetention or logRemovalPolicy, create a custom LogGroup using aws-cdk-lib/aws-logs and pass it to the logGroup property. This allows you to fully customize properties like retention and removal policies, which is not possible with the auto-created default log group.

Note on Regional Availability: Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. Check your region's availability before deploying.

import * as logs from 'aws-cdk-lib/aws-logs';

// Create a custom log group
const myLogGroup = new logs.LogGroup(this, 'MyLogGroup', {
  retention: logs.RetentionDays.ONE_WEEK,
});

// Pass it to the Edge Function props
// (Assuming the context of the construct using OptionalEdgeFunctionProps)
const props: OptionalEdgeFunctionProps = {
  logGroup: myLogGroup,
  // ... other props
};

The NextjsDomain construct simplifies the process of using a custom domain with Nextjs. It manages the interdependencies between a Route53 Hosted Zone, a CloudFront Distribution, and the necessary Route53 Hosted Zone Records.

Requirements:

• A Route53 hosted zone must exist within the same AWS account.
• If you use a different service for domain registration (like Cloudflare), you must still create a Route53 hosted zone and configure DNS delegation.

Alternative for external DNS: If you cannot use a Route53 hosted zone in the same account, use the overrides.nextjsDistribution.distributionProps property within NextjsProps to customize the distribution.

import { NextjsDomain } from 'cdk-nextjs-standalone';

// Initializing NextjsDomain
new NextjsDomain(scope, id, {
  domainName: 'example.com',
  alternateNames: ['www.example.com'],
  certificate: myCertificate, // aws-cdk-lib.aws_certificatemanager.ICertificate
  hostedZone: myHostedZone,   // aws-cdk-lib.aws_route53.IHostedZone
});