CDK Next.js Construct Library

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

Deploy Next.js apps on AWS with the AWS CDK.

Features

• Supports all features of Next.js App and Pages Router for Node.js Runtime
• Choose your AWS architecture for Next.js with the supported constructs: NextjsGlobalFunctions, NextjsGlobalContainers, NextjsRegionalContainers.
• Global Content Delivery Network (CDN) built with Amazon CloudFront to deliver content with low latency and high transfer speeds.
• Serverless functions powered by AWS Lambda or serverless containers powered by AWS Fargate.
• Static assets (JS, CSS, public folder) are stored and served from Amazon Simple Storage Service (S3) for global constructs to decrease latency and reduce compute costs.
• Optimized images, data cache, and full route cache are shared across compute with Amazon Elastic File System (EFS).
• Customize every construct via overrides.
• When using AWS Lambda for compute, async revalidation is supported with Amazon Simple Queue Service (SQS).
• AWS security and operational best practices are utilized, guided by cdk-nag.
• First class support for monorepos.
• AWS GovCloud (US) compatible (with NextjsRegionalContainers).

Getting Started

1. Install Docker. We recommend Rancher Desktop with dockerd (moby) container engine enabled.
2. Install Node.js. We recommend the long term support (LTS) version.
3. Set your next.config.js output key to "standalone". Learn more here about Standalone Output.
4. Setup AWS Cloud Development Kit app.
5. Install the construct package: npm install cdk-nextjs
6. cdk deploy
7. Visit URL printed in terminal (CloudFormation Output) to view your Next.js app!

Basic Example CDK App

import { App, Stack } from "aws-cdk-lib";
import { Construct } from "constructs";
import { fileURLToPath } from "node:url";
import { NextjsGlobalFunctions } from "cdk-nextjs";

class NextjsStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id, props);
    new NextjsGlobalFunctions(this, "Nextjs", {
      healthCheckPath: "/api/health",
      buildContext: fileURLToPath(new URL("..", import.meta.url)),
    });
  }
}

const app = new App();

new NextjsStack(app, "nextjs");

See examples/ for more usage examples.

Architecture

NextjsGlobalFunctions

NextjsGlobalContainers

NextjsRegionalContainers

Why

The simplest path to deploy Next.js is on Vercel - the Platform-as-a-Service company behind Next.js. However, deploying to Vercel can be expensive and some developers want all of their workloads running directly on AWS. Developers can deploy Next.js on AWS through AWS Amplify Hosting, but Amplify does not support all Next.js features and manages AWS resources for you so they cannot be customized. If Amplify meets your requirements we recommend you use it, but if you want to use all Next.js features or want more visibility into the AWS resources checkout cdk-nextjs.

Design Principles

• Treat Next.js as black box. Minimize reliance on Next.js internal APIs to reduce chance of incompatibility between this construct and future versions of Next.js.
• Security first.
• One size does not fit all.
• Enable customization everywhere.

Limitations

• If using NextjsGlobalFunctions or NextjsGlobalContainers (which use CloudFront), the number of top level files/directories cannot exceed 25, the max number of behaviors a CloudFront Distrubtion supports. We recommend you put all of your public assets into one top level directory (i.e. public/static) so you don't reach this limit. See CloudFront Quotas for more information.
• If using NextjsGlobalFunctions, when revalidating data in Next.js (i.e. revalidatePath), the CloudFront Cache will still hold stale data. You'll need to use AWS SDK JS V3 CreateInvalidationCommand to manually invalidate the path in CloudFront. See more here.
• If using NextjsGlobalFunctions, setting an Authorization header won't work by default because of Lambda Function URL with IAM Auth is already using the Authorization header. You can use the AWS_LWA_AUTHORIZATION_SOURCE environment variable of AWS Lambda Web Adapter to set an alternative Authorization header in the client which will then be set to the Authorization header when it reaches your app.

Additional Security Recommendations

This construct by default implements all AWS security best practices that a CDK construct library reasonably can considering cost and complexity. Below are additional security practices we recommend you implement within your CDK app. Please see them below:

• VPC Flow Logs. See examples/ for sample implementation.
• Scan ECR Images For Vulnerabilities.
• For NextjsGlobalFunctions and NextjsGlobalContainers, CloudFront Access Logs. See examples/ for sample implementation.
• For NextjsGlobalContainers and NextjsRegionalContainers, ALB HTTPS Listener

Estimated Costs

WIP

Acknowledgements

This construct was built on the shoulders of giants. Thank you to the contributors of cdk-nextjs-standalone and open-next.

Contributing

Steps to build locally:

1. git clone https://github.com/cdklabs/cdk-nextjs.git
2. cd cdk-nextjs
3. pnpm i && pnpm compile && pnpm build

This project uses Projen, so make sure to not edit Projen created files and only edit .projenrc.ts.

FAQ

Q: How does this compare to cdk-nextjs-standalone? A: cdk-nextjs-standalone relies on OpenNext. OpenNext injects custom code to interact with private Next.js APIs. While OpenNext is able to make some optimizations that are great for serverless environments, this comes at an increase maintenance cost and increased chances for breaking changes. A goal of cdk-nextjs is to customize Next.js as little as possible to reduce the maintenance burden and decrease chances of breaking changes.

Q: Why not offer API Gateway version of construct? A: API Gateway does not support streaming.

Q: Why EFS instead of S3? A: Next.js has 3 types of server caching that are persisted to disk: Data Cache, Full Route Cache, and Image Optimization. Cached data is persisted at .next/cache/fetch-cache, cached full routes are persisted at .next/server/app, and optimized images are persisted at .next/cache/images. Next.js provides a way to customize where cached data or cached full routes are persisted through the Custom Next.js Cache Handler, but there currently is no way to persist optimized images. Therefore, we need a way to persist cached data at the file system level which is transparent to Next.js. To do this, we use Amazon Elastic File System (EFS). Benefits of EFS include being able to cache any Next.js data persisted to disk and therefore being flexible to adapt to Next.js as the framework evolves caching additional types of data. One exception to not using the Custom Next.js Cache Handler is to support Data Cache Time-based Revalidation when using AWS Lambda functions. Functions only run when they are responding to a request preventing time-based revalidation unlike containers with AWS Fargate which run continually. For functions, an Amazon SQS Queue and consuming function that will make a HEAD request with x-prerender-revalidate header needed for Next.js to update cache.