OpenNext CDK
Deploy NextJS on AWS using CDK IaC and OpenNext packaging
### Contents
- [What is this?](#what-is-this)
- [Quickstart](#quickstart)
- [Requirements](#requirements)
- [Advanced](#advanced)
- [Pre-built OpenNext package](#pre-built-opennext-package)
- [Additional security](#additional-security)
- [About](#about)
- [Benefits](#benefits)
- [Dependencies](#dependencies)
- [Similar projects](#similar-projects)
- [Fork from cdk-nextjs](#fork-from-cdk-nextjs)
- [Contributing](#contributing)
- [Using Projen](#using-projen)
# What is this?
A building block for Amazon's infrastructure-as-code CDK toolkit to deploy a NextJS app using AWS serverless services.
Your NextJS app is packaged using OpenNext to fit the serverless format on Lambda
# Requirements
NextJs versions: >=12.3.0+ (includes 13.0.0+)
Platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64
# Quickstart
### NextJS setup
Add a dev dependency `esbuild@0.17.16` to your NextJS project.
```shell
npm install --save-dev esbuild@0.17.16
```
### CDK Construct
Use this construct in your CDK application to deploy your NextJS app to AWS.
Typescript 
Install the dependency using npm:
```shell
npm install --save-dev esbuild@0.17.16 open-next-cdk
```
Use the construct in your CDK application:
```ts
import { Nextjs } from 'open-next-cdk';
new Nextjs(this, 'Web', {
nextjsPath: './web', // relative path to nextjs project root
});
```
Java 
Install the dependency using Maven:
```xml
io.dataspray
open-next-cdk
x.y.z
```
Use the construct in your CDK application:
```java
Nextjs.Builder.create(this, getConstructId())
.nextjsPath("./web")
.build();
```
Go 
Install the dependency:
```shell
go get github.com:datasprayio/open-next-cdk.git@go
```
Or checkout [the code in the `go` branch](https://github.com/datasprayio/open-next-cdk/tree/go).
Python 
Install the dependency:
```shell
pip install open-next-cdk
```
.NET 
Install the dependency:
```shell
dotnet add package Dataspray.OpenNextCdk
```
This will automatically build your NextJS app and package it for you as part of the CDK construct.
If you would prefer to package it separately, see below:
# Advanced
### Pre-built OpenNext package
How-to
You may also provide already pre-built OpenNext package directly by building it yourself first:
```shell
open-next build
```
You will find a new folder `.open-next` which contains the packaging for your NextJS App. Now you can use the construct by instructing it not to build your app, just use the OpenNext folder directly:
```ts
import { Nextjs } from 'open-next-cdk';
new Nextjs(this, 'Web', {
openNextPath: './web/.open-next', // relative path to .open-next folder
});
```
### Additional security
How-to
```ts
import { RemovalPolicy, Stack } from "aws-cdk-lib";
import { Construct } from "constructs";
import { CfnWebAcl } from "aws-cdk-lib/aws-wafv2";
import { SecurityPolicyProtocol, type DistributionProps } from "aws-cdk-lib/aws-cloudfront";
import { Nextjs, type NextjsDistributionProps } from "cdk-nextjs-standalone";
import { Bucket, BlockPublicAccess, BucketEncryption } from "aws-cdk-lib/aws-s3";
// Because of `WebAcl`, this stack must be deployed in us-east-1. If you want
// to deploy Nextjs in another region, add WAF in separate stack deployed in us-east-1
export class UiStack {
constructor(scope: Construct, id: string) {
const webAcl = new CfnWebAcl(this, "WebAcl", { ... });
new Nextjs(this, "NextSite", {
nextjsPath: "...",
defaults: {
assetDeployment: {
bucket: new Bucket(this, "NextjsAssetDeploymentBucket", {
autoDeleteObjects: true,
removalPolicy: RemovalPolicy.DESTROY,
encryption: BucketEncryption.S3_MANAGED,
enforceSSL: true,
blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
}),
},
distribution: {
functionUrlAuthType: FunctionUrlAuthType.AWS_IAM,
cdk: {
distribution: {
webAclId: webAcl.attrArn,
minimumProtocolVersion: SecurityPolicyProtocol.TLS_V1_2_2021,
} as DistributionProps,
},
} satisfies Partial,
},
});
}
}
```
# About
Deploys a NextJs static site with server-side rendering and API support. Uses AWS lambda and CloudFront.
There is a new (since Next 12) [standalone output mode which uses output tracing](https://nextjs.org/docs/advanced-features/output-file-tracing) to generate a minimal server and static files.
This standalone server can be converted into a CloudFront distribution and a lambda handler that handles SSR, API, and routing.
The CloudFront default origin first checks S3 for static files and falls back to an HTTP origin using a lambda function URL.
## Benefits
This approach is most compatible with new NextJs features such as ESM configuration, [middleware](https://nextjs.org/docs/advanced-features/middleware), next-auth, and React server components ("appDir").
The unmaintained [@serverless-nextjs project](https://github.com/serverless-nextjs/serverless-next.js) uses the deprecated `serverless` NextJs build target which [prevents the use of new features](https://github.com/serverless-nextjs/serverless-next.js/pull/2478).
This construct was created to use the new `standalone` output build and newer AWS features like lambda function URLs and fallback origins.
You may want to look at [Serverless Stack](https://sst.dev) and its [NextjsSite](https://docs.sst.dev/constructs/NextjsSite) construct for an improved developer experience if you are building serverless applications on CDK.
## Dependencies
Built on top of [open-next](https://open-next.js.org/), which was partially built using the original core of cdk-nextjs-standalone.
## Similar projects
This project is heavily based on
- [Open-next](https://open-next.js.org/)
-
-
-
- [Serverless Stack](https://github.com/serverless-stack/sst)
- [RemixSite](https://github.com/serverless-stack/sst/blob/master/packages/resources/src/NextjsSite.ts) construct
- [NextjsSite](https://github.com/serverless-stack/sst/blob/master/packages/resources/src/RemixSite.ts) construct
### Fork from cdk-nextjs
Compatible with: `cdk-nextjs`[@3.2.1](https://github.com/jetbridge/cdk-nextjs/releases/tag/v3.2.1)
This project has been initially forked from [cdk-nextjs](https://github.com/jetbridge/cdk-nextjs) in order to [publish the package to other langugages](https://github.com/jetbridge/cdk-nextjs/issues/120#issuecomment-1634926223). So far notable changes are:
- Extended language support: TS, Java, Go, .NET, Python.
- Extended platform support: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64
- Use pre-built open-next package
# Contributing
Hey there, we value every new contribution a lot 🙏🏼 thank you. Open an issue or a PR and we'll gladly help you out.
## Using Projen
Most boilerplate files are pre-generated including package.json. Don't update it directly, rather update `.projenrc.js` then run `yarn projen` to re-generate the files.
