Skip to content

Latest commit

 

History

History
2760 lines (1685 loc) · 97.3 KB

API.md

File metadata and controls

2760 lines (1685 loc) · 97.3 KB
Raw

API Reference

Constructs

Nextjs

The Nextjs construct is a higher level CDK construct that makes it easy to create a NextJS app.

Your standalone server application will be bundled using output tracing and will be deployed to a Lambda function. Static assets will be deployed to an S3 bucket and served via CloudFront. You must use Next.js 10.3.0 or newer.

Please provide a nextjsPath to the Next.js app inside your project.

Example

new Nextjs(this, "Web", {
  nextjsPath: path.resolve("packages/web"),
})

Initializers 

import { Nextjs } from 'cdk-nextjs-standalone'

new Nextjs(scope: Construct, id: string, props: NextjsProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NextjsProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { Nextjs } from 'cdk-nextjs-standalone'

Nextjs.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
imageCachePolicyProps aws-cdk-lib.aws_cloudfront.CachePolicyProps The default CloudFront cache policy properties for images.
lambdaCachePolicyProps aws-cdk-lib.aws_cloudfront.CachePolicyProps The default CloudFront cache policy properties for the Lambda server handler.
lambdaOriginRequestPolicyProps aws-cdk-lib.aws_cloudfront.OriginRequestPolicyProps The default CloudFront lambda origin request policy.
staticCachePolicyProps aws-cdk-lib.aws_cloudfront.CachePolicyProps The default CloudFront cache policy properties for static pages.
bucketArn string The ARN of the internally created S3 Bucket.
bucketName string The name of the internally created S3 Bucket.
distributionDomain string The domain name of the internally created CloudFront Distribution.
distributionId string The ID of the internally created CloudFront Distribution.
url string The CloudFront URL of the website.
customDomainUrl string If the custom domain is enabled, this is the URL of the website with the custom domain.
assetsDeployment NextJsAssetsDeployment Asset deployment to S3.
bucket aws-cdk-lib.aws_s3.IBucket Bucket containing NextJS static assets.
distribution aws-cdk-lib.aws_cloudfront.Distribution The internally created CDK Distribution instance.
lambdaFunctionUrl aws-cdk-lib.aws_lambda.FunctionUrl No description.
nextBuild NextjsBuild Built NextJS project output.
originAccessIdentity aws-cdk-lib.aws_cloudfront.IOriginAccessIdentity No description.
serverFunction NextJsLambda The main NextJS server handler lambda function.
tempBuildDir string No description.
certificate aws-cdk-lib.aws_certificatemanager.ICertificate The AWS Certificate Manager certificate for the custom domain.
configBucket aws-cdk-lib.aws_s3.Bucket No description.
hostedZone aws-cdk-lib.aws_route53.IHostedZone The Route 53 hosted zone for the custom domain.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

imageCachePolicyPropsRequired 
public readonly imageCachePolicyProps: CachePolicyProps;
  • Type: aws-cdk-lib.aws_cloudfront.CachePolicyProps

The default CloudFront cache policy properties for images.

lambdaCachePolicyPropsRequired 
public readonly lambdaCachePolicyProps: CachePolicyProps;
  • Type: aws-cdk-lib.aws_cloudfront.CachePolicyProps

The default CloudFront cache policy properties for the Lambda server handler.

lambdaOriginRequestPolicyPropsRequired 
public readonly lambdaOriginRequestPolicyProps: OriginRequestPolicyProps;
  • Type: aws-cdk-lib.aws_cloudfront.OriginRequestPolicyProps

The default CloudFront lambda origin request policy.

staticCachePolicyPropsRequired 
public readonly staticCachePolicyProps: CachePolicyProps;
  • Type: aws-cdk-lib.aws_cloudfront.CachePolicyProps

The default CloudFront cache policy properties for static pages.

bucketArnRequired 
public readonly bucketArn: string;
  • Type: string

The ARN of the internally created S3 Bucket.

bucketNameRequired 
public readonly bucketName: string;
  • Type: string

The name of the internally created S3 Bucket.

distributionDomainRequired 
public readonly distributionDomain: string;
  • Type: string

The domain name of the internally created CloudFront Distribution.

distributionIdRequired 
public readonly distributionId: string;
  • Type: string

The ID of the internally created CloudFront Distribution.

urlRequired 
public readonly url: string;
  • Type: string

The CloudFront URL of the website.

customDomainUrlOptional 
public readonly customDomainUrl: string;
  • Type: string

If the custom domain is enabled, this is the URL of the website with the custom domain.

assetsDeploymentRequired 
public readonly assetsDeployment: NextJsAssetsDeployment;

Asset deployment to S3.

bucketRequired 
public readonly bucket: IBucket;
  • Type: aws-cdk-lib.aws_s3.IBucket

Bucket containing NextJS static assets.

distributionRequired 
public readonly distribution: Distribution;
  • Type: aws-cdk-lib.aws_cloudfront.Distribution

The internally created CDK Distribution instance.

lambdaFunctionUrlRequired 
public readonly lambdaFunctionUrl: FunctionUrl;
  • Type: aws-cdk-lib.aws_lambda.FunctionUrl
nextBuildRequired 
public readonly nextBuild: NextjsBuild;

Built NextJS project output.

originAccessIdentityRequired 
public readonly originAccessIdentity: IOriginAccessIdentity;
  • Type: aws-cdk-lib.aws_cloudfront.IOriginAccessIdentity
serverFunctionRequired 
public readonly serverFunction: NextJsLambda;

The main NextJS server handler lambda function.

tempBuildDirRequired 
public readonly tempBuildDir: string;
  • Type: string
certificateOptional 
public readonly certificate: ICertificate;
  • Type: aws-cdk-lib.aws_certificatemanager.ICertificate

The AWS Certificate Manager certificate for the custom domain.

configBucketOptional 
public readonly configBucket: Bucket;
  • Type: aws-cdk-lib.aws_s3.Bucket
hostedZoneOptional 
public readonly hostedZone: IHostedZone;
  • Type: aws-cdk-lib.aws_route53.IHostedZone

The Route 53 hosted zone for the custom domain.

NextJsAssetsDeployment

Uploads NextJS-built static and public files to S3.

Will rewrite CloudFormation references with their resolved values after uploading.

Initializers 

import { NextJsAssetsDeployment } from 'cdk-nextjs-standalone'

new NextJsAssetsDeployment(scope: Construct, id: string, props: NextjsAssetsDeploymentProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NextjsAssetsDeploymentProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { NextJsAssetsDeployment } from 'cdk-nextjs-standalone'

NextJsAssetsDeployment.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
bucket aws-cdk-lib.aws_s3.IBucket Bucket containing assets.
deployments aws-cdk-lib.aws_s3_deployment.BucketDeployment[] Asset deployments to S3.
staticTempDir string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

bucketRequired 
public readonly bucket: IBucket;
  • Type: aws-cdk-lib.aws_s3.IBucket

Bucket containing assets.

deploymentsRequired 
public readonly deployments: BucketDeployment[];
  • Type: aws-cdk-lib.aws_s3_deployment.BucketDeployment[]

Asset deployments to S3.

staticTempDirRequired 
public readonly staticTempDir: string;
  • Type: string

NextjsBuild

Represents a built NextJS application.

This construct runs npm build in standalone output mode inside your nextjsPath. This construct can be used by higher level constructs or used directly.

Initializers 

import { NextjsBuild } from 'cdk-nextjs-standalone'

new NextjsBuild(scope: Construct, id: string, props: NextjsBuildProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NextjsBuildProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
readPublicFileList No description.
toString 
public toString(): string

Returns a string representation of this construct.

readPublicFileList 
public readPublicFileList(): string[]

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { NextjsBuild } from 'cdk-nextjs-standalone'

NextjsBuild.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
buildPath string The path to the directory where the server build artifacts are stored.
nextPublicDir string Public static files.
nextStandaloneBuildDir string NextJS project inside of standalone build.
nextStandaloneDir string Entire NextJS build output directory.
nextStaticDir string Static files containing client-side code.
props NextjsBuildProps No description.
tempBuildDir string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

buildPathRequired 
public readonly buildPath: string;
  • Type: string

The path to the directory where the server build artifacts are stored.

nextPublicDirRequired 
public readonly nextPublicDir: string;
  • Type: string

Public static files.

E.g. robots.txt, favicon.ico, etc.

nextStandaloneBuildDirRequired 
public readonly nextStandaloneBuildDir: string;
  • Type: string

NextJS project inside of standalone build.

Contains server code and manifests.

nextStandaloneDirRequired 
public readonly nextStandaloneDir: string;
  • Type: string

Entire NextJS build output directory.

Contains server and client code and manifests.

nextStaticDirRequired 
public readonly nextStaticDir: string;
  • Type: string

Static files containing client-side code.

propsRequired 
public readonly props: NextjsBuildProps;
tempBuildDirRequired 
public readonly tempBuildDir: string;
  • Type: string

NextJsLambda

Build a lambda function from a NextJS application to handle server-side rendering, API routes, and image optimization.

Initializers 

import { NextJsLambda } from 'cdk-nextjs-standalone'

new NextJsLambda(scope: Construct, id: string, props: NextjsLambdaProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NextjsLambdaProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { NextJsLambda } from 'cdk-nextjs-standalone'

NextJsLambda.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
lambdaFunction aws-cdk-lib.aws_lambda.Function No description.
configBucket aws-cdk-lib.aws_s3.Bucket No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

lambdaFunctionRequired 
public readonly lambdaFunction: Function;
  • Type: aws-cdk-lib.aws_lambda.Function
configBucketOptional 
public readonly configBucket: Bucket;
  • Type: aws-cdk-lib.aws_s3.Bucket

NextjsLayer

Lambda layer for Next.js. Contains Sharp 0.30.0.

Initializers 

import { NextjsLayer } from 'cdk-nextjs-standalone'

new NextjsLayer(scope: Construct, id: string, props: NextjsLayerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NextjsLayerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addPermission Add permission for this layer version to specific entities.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addPermission 
public addPermission(id: string, permission: LayerVersionPermission): void

Add permission for this layer version to specific entities.

Usage within the same account where the layer is defined is always allowed and does not require calling this method. Note that the principal that creates the Lambda function using the layer (for example, a CloudFormation changeset execution role) also needs to have the lambda:GetLayerVersion permission on the layer version.

idRequired
  • Type: string
permissionRequired
  • Type: aws-cdk-lib.aws_lambda.LayerVersionPermission

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
fromLayerVersionArn Imports a layer version by ARN.
fromLayerVersionAttributes Imports a Layer that has been defined externally.
isConstruct 
import { NextjsLayer } from 'cdk-nextjs-standalone'

NextjsLayer.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { NextjsLayer } from 'cdk-nextjs-standalone'

NextjsLayer.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { NextjsLayer } from 'cdk-nextjs-standalone'

NextjsLayer.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromLayerVersionArn 
import { NextjsLayer } from 'cdk-nextjs-standalone'

NextjsLayer.fromLayerVersionArn(scope: Construct, id: string, layerVersionArn: string)

Imports a layer version by ARN.

Assumes it is compatible with all Lambda runtimes.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
layerVersionArnRequired
  • Type: string
fromLayerVersionAttributes 
import { NextjsLayer } from 'cdk-nextjs-standalone'

NextjsLayer.fromLayerVersionAttributes(scope: Construct, id: string, attrs: LayerVersionAttributes)

Imports a Layer that has been defined externally.

scopeRequired
  • Type: constructs.Construct

the parent Construct that will use the imported layer.

idRequired
  • Type: string

the id of the imported layer in the construct tree.

attrsRequired
  • Type: aws-cdk-lib.aws_lambda.LayerVersionAttributes

the properties of the imported layer.

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
layerVersionArn string The ARN of the Lambda Layer version that this Layer defines.
compatibleRuntimes aws-cdk-lib.aws_lambda.Runtime[] The runtimes compatible with this Layer.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

layerVersionArnRequired 
public readonly layerVersionArn: string;
  • Type: string

The ARN of the Lambda Layer version that this Layer defines.

compatibleRuntimesOptional 
public readonly compatibleRuntimes: Runtime[];
  • Type: aws-cdk-lib.aws_lambda.Runtime[]

The runtimes compatible with this Layer.

Structs

BaseSiteDomainProps

Initializer 

import { BaseSiteDomainProps } from 'cdk-nextjs-standalone'

const baseSiteDomainProps: BaseSiteDomainProps = { ... }

Properties

Name Type Description
domainName string The domain to be assigned to the website URL (ie. domain.com).
alternateNames string[] Specify additional names that should route to the Cloudfront Distribution.
certificate aws-cdk-lib.aws_certificatemanager.ICertificate Import the certificate for the domain.
domainAlias string An alternative domain to be assigned to the website URL.
hostedZone aws-cdk-lib.aws_route53.IHostedZone Import the underlying Route 53 hosted zone.
isExternalDomain boolean Set this option if the domain is not hosted on Amazon Route 53.
domainNameRequired 
public readonly domainName: string;
  • Type: string

The domain to be assigned to the website URL (ie. domain.com).

Supports domains that are hosted either on Route 53 or externally.

alternateNamesOptional 
public readonly alternateNames: string[];
  • Type: string[]

Specify additional names that should route to the Cloudfront Distribution.

Note, certificates for these names will not be automatically generated so the certificate option must be specified.

certificateOptional 
public readonly certificate: ICertificate;
  • Type: aws-cdk-lib.aws_certificatemanager.ICertificate

Import the certificate for the domain.

By default, SST will create a certificate with the domain name. The certificate will be created in the us-east-1(N. Virginia) region as required by AWS CloudFront.

Set this option if you have an existing certificate in the us-east-1 region in AWS Certificate Manager you want to use.

domainAliasOptional 
public readonly domainAlias: string;
  • Type: string

An alternative domain to be assigned to the website URL.

Visitors to the alias will be redirected to the main domain. (ie. www.domain.com).

Use this to create a www. version of your domain and redirect visitors to the root domain.

hostedZoneOptional 
public readonly hostedZone: IHostedZone;
  • Type: aws-cdk-lib.aws_route53.IHostedZone

Import the underlying Route 53 hosted zone.

isExternalDomainOptional 
public readonly isExternalDomain: boolean;
  • Type: boolean

Set this option if the domain is not hosted on Amazon Route 53.

BaseSiteEnvironmentOutputsInfo

Initializer 

import { BaseSiteEnvironmentOutputsInfo } from 'cdk-nextjs-standalone'

const baseSiteEnvironmentOutputsInfo: BaseSiteEnvironmentOutputsInfo = { ... }

Properties

Name Type Description
environmentOutputs {[ key: string ]: string} No description.
path string No description.
stack string No description.
environmentOutputsRequired 
public readonly environmentOutputs: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
pathRequired 
public readonly path: string;
  • Type: string
stackRequired 
public readonly stack: string;
  • Type: string

BaseSiteReplaceProps

Initializer 

import { BaseSiteReplaceProps } from 'cdk-nextjs-standalone'

const baseSiteReplaceProps: BaseSiteReplaceProps = { ... }

Properties

Name Type Description
files string No description.
replace string No description.
search string No description.
filesRequired 
public readonly files: string;
  • Type: string
replaceRequired 
public readonly replace: string;
  • Type: string
searchRequired 
public readonly search: string;
  • Type: string

CreateArchiveArgs

Initializer 

import { CreateArchiveArgs } from 'cdk-nextjs-standalone'

const createArchiveArgs: CreateArchiveArgs = { ... }

Properties

Name Type Description
directory string No description.
zipFileName string No description.
zipOutDir string No description.
compressionLevel number No description.
fileGlob string No description.
quiet boolean No description.
directoryRequired 
public readonly directory: string;
  • Type: string
zipFileNameRequired 
public readonly zipFileName: string;
  • Type: string
zipOutDirRequired 
public readonly zipOutDir: string;
  • Type: string
compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
fileGlobOptional 
public readonly fileGlob: string;
  • Type: string
quietOptional 
public readonly quiet: boolean;
  • Type: boolean

NextjsAssetsDeploymentProps

Initializer 

import { NextjsAssetsDeploymentProps } from 'cdk-nextjs-standalone'

const nextjsAssetsDeploymentProps: NextjsAssetsDeploymentProps = { ... }

Properties

Name Type Description
nextjsPath string Relative path to the directory where the NextJS project is located.
compressionLevel number 0 - no compression, fatest 9 - maximum compression, slowest.
environment {[ key: string ]: string} Custom environment variables to pass to the NextJS build and runtime.
isPlaceholder boolean Skip building app and deploy a placeholder.
nodeEnv string Optional value for NODE_ENV during build and runtime.
quiet boolean Less build output.
tempBuildDir string Directory to store temporary build files in.
nextBuild NextjsBuild The NextjsBuild instance representing the built Nextjs application.
bucket aws-cdk-lib.aws_s3.IBucket | aws-cdk-lib.aws_s3.BucketProps Properties for the S3 bucket containing the NextJS assets.
distribution aws-cdk-lib.aws_cloudfront.IDistribution Distribution to invalidate when assets change.
prune boolean Set to true to delete old assets (defaults to false).
nextjsPathRequired 
public readonly nextjsPath: string;
  • Type: string

Relative path to the directory where the NextJS project is located.

Can be the root of your project (.) or a subdirectory (packages/web).

compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
  • Default: 1

0 - no compression, fatest 9 - maximum compression, slowest.

environmentOptional 
public readonly environment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Custom environment variables to pass to the NextJS build and runtime.

isPlaceholderOptional 
public readonly isPlaceholder: boolean;
  • Type: boolean

Skip building app and deploy a placeholder.

Useful when using next dev for local development.

nodeEnvOptional 
public readonly nodeEnv: string;
  • Type: string

Optional value for NODE_ENV during build and runtime.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean

Less build output.

tempBuildDirOptional 
public readonly tempBuildDir: string;
  • Type: string

Directory to store temporary build files in.

Defaults to os.tmpdir().

nextBuildRequired 
public readonly nextBuild: NextjsBuild;

The NextjsBuild instance representing the built Nextjs application.

bucketOptional 
public readonly bucket: IBucket | BucketProps;
  • Type: aws-cdk-lib.aws_s3.IBucket | aws-cdk-lib.aws_s3.BucketProps

Properties for the S3 bucket containing the NextJS assets.

You can also supply your own bucket here.

distributionOptional 
public readonly distribution: IDistribution;
  • Type: aws-cdk-lib.aws_cloudfront.IDistribution

Distribution to invalidate when assets change.

pruneOptional 
public readonly prune: boolean;
  • Type: boolean

Set to true to delete old assets (defaults to false).

Recommended to only set to true if you don't need the ability to roll back deployments.

NextjsBaseProps

Common props shared across NextJS-related CDK constructs.

Initializer 

import { NextjsBaseProps } from 'cdk-nextjs-standalone'

const nextjsBaseProps: NextjsBaseProps = { ... }

Properties

Name Type Description
nextjsPath string Relative path to the directory where the NextJS project is located.
compressionLevel number 0 - no compression, fatest 9 - maximum compression, slowest.
environment {[ key: string ]: string} Custom environment variables to pass to the NextJS build and runtime.
isPlaceholder boolean Skip building app and deploy a placeholder.
nodeEnv string Optional value for NODE_ENV during build and runtime.
quiet boolean Less build output.
tempBuildDir string Directory to store temporary build files in.
nextjsPathRequired 
public readonly nextjsPath: string;
  • Type: string

Relative path to the directory where the NextJS project is located.

Can be the root of your project (.) or a subdirectory (packages/web).

compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
  • Default: 1

0 - no compression, fatest 9 - maximum compression, slowest.

environmentOptional 
public readonly environment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Custom environment variables to pass to the NextJS build and runtime.

isPlaceholderOptional 
public readonly isPlaceholder: boolean;
  • Type: boolean

Skip building app and deploy a placeholder.

Useful when using next dev for local development.

nodeEnvOptional 
public readonly nodeEnv: string;
  • Type: string

Optional value for NODE_ENV during build and runtime.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean

Less build output.

tempBuildDirOptional 
public readonly tempBuildDir: string;
  • Type: string

Directory to store temporary build files in.

Defaults to os.tmpdir().

NextjsBuildProps

Initializer 

import { NextjsBuildProps } from 'cdk-nextjs-standalone'

const nextjsBuildProps: NextjsBuildProps = { ... }

Properties

Name Type Description
nextjsPath string Relative path to the directory where the NextJS project is located.
compressionLevel number 0 - no compression, fatest 9 - maximum compression, slowest.
environment {[ key: string ]: string} Custom environment variables to pass to the NextJS build and runtime.
isPlaceholder boolean Skip building app and deploy a placeholder.
nodeEnv string Optional value for NODE_ENV during build and runtime.
quiet boolean Less build output.
tempBuildDir string Directory to store temporary build files in.
nextjsPathRequired 
public readonly nextjsPath: string;
  • Type: string

Relative path to the directory where the NextJS project is located.

Can be the root of your project (.) or a subdirectory (packages/web).

compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
  • Default: 1

0 - no compression, fatest 9 - maximum compression, slowest.

environmentOptional 
public readonly environment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Custom environment variables to pass to the NextJS build and runtime.

isPlaceholderOptional 
public readonly isPlaceholder: boolean;
  • Type: boolean

Skip building app and deploy a placeholder.

Useful when using next dev for local development.

nodeEnvOptional 
public readonly nodeEnv: string;
  • Type: string

Optional value for NODE_ENV during build and runtime.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean

Less build output.

tempBuildDirOptional 
public readonly tempBuildDir: string;
  • Type: string

Directory to store temporary build files in.

Defaults to os.tmpdir().

NextjsCachePolicyProps

Initializer 

import { NextjsCachePolicyProps } from 'cdk-nextjs-standalone'

const nextjsCachePolicyProps: NextjsCachePolicyProps = { ... }

Properties

Name Type Description
imageCachePolicy aws-cdk-lib.aws_cloudfront.ICachePolicy No description.
lambdaCachePolicy aws-cdk-lib.aws_cloudfront.ICachePolicy No description.
staticCachePolicy aws-cdk-lib.aws_cloudfront.ICachePolicy No description.
imageCachePolicyOptional 
public readonly imageCachePolicy: ICachePolicy;
  • Type: aws-cdk-lib.aws_cloudfront.ICachePolicy
lambdaCachePolicyOptional 
public readonly lambdaCachePolicy: ICachePolicy;
  • Type: aws-cdk-lib.aws_cloudfront.ICachePolicy
staticCachePolicyOptional 
public readonly staticCachePolicy: ICachePolicy;
  • Type: aws-cdk-lib.aws_cloudfront.ICachePolicy

NextjsCdkDistributionProps

Initializer 

import { NextjsCdkDistributionProps } from 'cdk-nextjs-standalone'

const nextjsCdkDistributionProps: NextjsCdkDistributionProps = { ... }

Properties

Name Type Description
defaultBehavior aws-cdk-lib.aws_cloudfront.BehaviorOptions The default behavior for the distribution.
additionalBehaviors {[ key: string ]: aws-cdk-lib.aws_cloudfront.BehaviorOptions} Additional behaviors for the distribution, mapped by the pathPattern that specifies which requests to apply the behavior to.
certificate aws-cdk-lib.aws_certificatemanager.ICertificate A certificate to associate with the distribution.
comment string Any comments you want to include about the distribution.
defaultRootObject string The object that you want CloudFront to request from your origin (for example, index.html) when a viewer requests the root URL for your distribution. If no default object is set, the request goes to the origin's root (e.g., example.com/).
domainNames string[] Alternative domain names for this distribution.
enabled boolean Enable or disable the distribution.
enableIpv6 boolean Whether CloudFront will respond to IPv6 DNS requests with an IPv6 address.
enableLogging boolean Enable access logging for the distribution.
errorResponses aws-cdk-lib.aws_cloudfront.ErrorResponse[] How CloudFront should handle requests that are not successful (e.g., PageNotFound).
geoRestriction aws-cdk-lib.aws_cloudfront.GeoRestriction Controls the countries in which your content is distributed.
httpVersion aws-cdk-lib.aws_cloudfront.HttpVersion Specify the maximum HTTP version that you want viewers to use to communicate with CloudFront.
logBucket aws-cdk-lib.aws_s3.IBucket The Amazon S3 bucket to store the access logs in.
logFilePrefix string An optional string that you want CloudFront to prefix to the access log filenames for this distribution.
logIncludesCookies boolean Specifies whether you want CloudFront to include cookies in access logs.
minimumProtocolVersion aws-cdk-lib.aws_cloudfront.SecurityPolicyProtocol The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections.
priceClass aws-cdk-lib.aws_cloudfront.PriceClass The price class that corresponds with the maximum price that you want to pay for CloudFront service.
sslSupportMethod aws-cdk-lib.aws_cloudfront.SSLMethod The SSL method CloudFront will use for your distribution.
webAclId string Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.
defaultBehaviorRequired 
public readonly defaultBehavior: BehaviorOptions;
  • Type: aws-cdk-lib.aws_cloudfront.BehaviorOptions

The default behavior for the distribution.

additionalBehaviorsOptional 
public readonly additionalBehaviors: {[ key: string ]: BehaviorOptions};
  • Type: {[ key: string ]: aws-cdk-lib.aws_cloudfront.BehaviorOptions}
  • Default: no additional behaviors are added.

Additional behaviors for the distribution, mapped by the pathPattern that specifies which requests to apply the behavior to.

certificateOptional 
public readonly certificate: ICertificate;
  • Type: aws-cdk-lib.aws_certificatemanager.ICertificate
  • Default: the CloudFront wildcard certificate (*.cloudfront.net) will be used.

A certificate to associate with the distribution.

The certificate must be located in N. Virginia (us-east-1).

commentOptional 
public readonly comment: string;
  • Type: string
  • Default: no comment

Any comments you want to include about the distribution.

defaultRootObjectOptional 
public readonly defaultRootObject: string;
  • Type: string
  • Default: no default root object

The object that you want CloudFront to request from your origin (for example, index.html) when a viewer requests the root URL for your distribution. If no default object is set, the request goes to the origin's root (e.g., example.com/).

domainNamesOptional 
public readonly domainNames: string[];
  • Type: string[]
  • Default: The distribution will only support the default generated name (e.g., d111111abcdef8.cloudfront.net)

Alternative domain names for this distribution.

If you want to use your own domain name, such as www.example.com, instead of the cloudfront.net domain name, you can add an alternate domain name to your distribution. If you attach a certificate to the distribution, you must add (at least one of) the domain names of the certificate to this list.

enabledOptional 
public readonly enabled: boolean;
  • Type: boolean
  • Default: true

Enable or disable the distribution.

enableIpv6Optional 
public readonly enableIpv6: boolean;
  • Type: boolean
  • Default: true

Whether CloudFront will respond to IPv6 DNS requests with an IPv6 address.

If you specify false, CloudFront responds to IPv6 DNS requests with the DNS response code NOERROR and with no IP addresses. This allows viewers to submit a second request, for an IPv4 address for your distribution.

enableLoggingOptional 
public readonly enableLogging: boolean;
  • Type: boolean
  • Default: false, unless logBucket is specified.

Enable access logging for the distribution.

errorResponsesOptional 
public readonly errorResponses: ErrorResponse[];
  • Type: aws-cdk-lib.aws_cloudfront.ErrorResponse[]
  • Default: No custom error responses.

How CloudFront should handle requests that are not successful (e.g., PageNotFound).

geoRestrictionOptional 
public readonly geoRestriction: GeoRestriction;
  • Type: aws-cdk-lib.aws_cloudfront.GeoRestriction
  • Default: No geographic restrictions

Controls the countries in which your content is distributed.

httpVersionOptional 
public readonly httpVersion: HttpVersion;
  • Type: aws-cdk-lib.aws_cloudfront.HttpVersion
  • Default: HttpVersion.HTTP2

Specify the maximum HTTP version that you want viewers to use to communicate with CloudFront.

For viewers and CloudFront to use HTTP/2, viewers must support TLS 1.2 or later, and must support server name identification (SNI).

logBucketOptional 
public readonly logBucket: IBucket;
  • Type: aws-cdk-lib.aws_s3.IBucket
  • Default: A bucket is created if enableLogging is true

The Amazon S3 bucket to store the access logs in.

logFilePrefixOptional 
public readonly logFilePrefix: string;
  • Type: string
  • Default: no prefix

An optional string that you want CloudFront to prefix to the access log filenames for this distribution.

logIncludesCookiesOptional 
public readonly logIncludesCookies: boolean;
  • Type: boolean
  • Default: false

Specifies whether you want CloudFront to include cookies in access logs.

minimumProtocolVersionOptional 
public readonly minimumProtocolVersion: SecurityPolicyProtocol;
  • Type: aws-cdk-lib.aws_cloudfront.SecurityPolicyProtocol
  • Default: SecurityPolicyProtocol.TLS_V1_2_2021 if the '

The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections.

CloudFront serves your objects only to browsers or devices that support at least the SSL version that you specify.

priceClassOptional 
public readonly priceClass: PriceClass;
  • Type: aws-cdk-lib.aws_cloudfront.PriceClass
  • Default: PriceClass.PRICE_CLASS_ALL

The price class that corresponds with the maximum price that you want to pay for CloudFront service.

If you specify PriceClass_All, CloudFront responds to requests for your objects from all CloudFront edge locations. If you specify a price class other than PriceClass_All, CloudFront serves your objects from the CloudFront edge location that has the lowest latency among the edge locations in your price class.

sslSupportMethodOptional 
public readonly sslSupportMethod: SSLMethod;
  • Type: aws-cdk-lib.aws_cloudfront.SSLMethod
  • Default: SSLMethod.SNI

The SSL method CloudFront will use for your distribution.

Server Name Indication (SNI) - is an extension to the TLS computer networking protocol by which a client indicates which hostname it is attempting to connect to at the start of the handshaking process. This allows a server to present multiple certificates on the same IP address and TCP port number and hence allows multiple secure (HTTPS) websites (or any other service over TLS) to be served by the same IP address without requiring all those sites to use the same certificate.

CloudFront can use SNI to host multiple distributions on the same IP - which a large majority of clients will support.

If your clients cannot support SNI however - CloudFront can use dedicated IPs for your distribution - but there is a prorated monthly charge for using this feature. By default, we use SNI - but you can optionally enable dedicated IPs (VIP).

See the CloudFront SSL for more details about pricing : https://aws.amazon.com/cloudfront/custom-ssl-domains/

webAclIdOptional 
public readonly webAclId: string;
  • Type: string
  • Default: No AWS Web Application Firewall web access control list (web ACL).

Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.

To specify a web ACL created using the latest version of AWS WAF, use the ACL ARN, for example arn:aws:wafv2:us-east-1:123456789012:global/webacl/ExampleWebACL/473e64fd-f30b-4765-81a0-62ad96dd167a. To specify a web ACL created using AWS WAF Classic, use the ACL ID, for example 473e64fd-f30b-4765-81a0-62ad96dd167a.

https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html#API_CreateDistribution_RequestParameters.

NextjsCdkProps

Resources that will be created automatically if not supplied.

Initializer 

import { NextjsCdkProps } from 'cdk-nextjs-standalone'

const nextjsCdkProps: NextjsCdkProps = { ... }

Properties

Name Type Description
cachePolicies NextjsCachePolicyProps Override the default CloudFront cache policies created internally.
deployment NextjsAssetsDeploymentProps Override static file deployment settings.
distribution NextjsCdkDistributionProps Pass in a value to override the default settings this construct uses to create the CDK Distribution internally.
lambda NextjsLambdaProps Override server lambda function settings.
lambdaOriginRequestPolicy aws-cdk-lib.aws_cloudfront.IOriginRequestPolicy Override the default CloudFront lambda origin request policy created internally.
cachePoliciesOptional 
public readonly cachePolicies: NextjsCachePolicyProps;

Override the default CloudFront cache policies created internally.

deploymentOptional 
public readonly deployment: NextjsAssetsDeploymentProps;

Override static file deployment settings.

distributionOptional 
public readonly distribution: NextjsCdkDistributionProps;

Pass in a value to override the default settings this construct uses to create the CDK Distribution internally.

lambdaOptional 
public readonly lambda: NextjsLambdaProps;

Override server lambda function settings.

lambdaOriginRequestPolicyOptional 
public readonly lambdaOriginRequestPolicy: IOriginRequestPolicy;
  • Type: aws-cdk-lib.aws_cloudfront.IOriginRequestPolicy

Override the default CloudFront lambda origin request policy created internally.

NextjsDomainProps

Initializer 

import { NextjsDomainProps } from 'cdk-nextjs-standalone'

const nextjsDomainProps: NextjsDomainProps = { ... }

Properties

Name Type Description
domainName string The domain to be assigned to the website URL (ie. domain.com).
alternateNames string[] Specify additional names that should route to the Cloudfront Distribution.
certificate aws-cdk-lib.aws_certificatemanager.ICertificate Import the certificate for the domain.
domainAlias string An alternative domain to be assigned to the website URL.
hostedZone aws-cdk-lib.aws_route53.IHostedZone Import the underlying Route 53 hosted zone.
isExternalDomain boolean Set this option if the domain is not hosted on Amazon Route 53.
domainNameRequired 
public readonly domainName: string;
  • Type: string

The domain to be assigned to the website URL (ie. domain.com).

Supports domains that are hosted either on Route 53 or externally.

alternateNamesOptional 
public readonly alternateNames: string[];
  • Type: string[]

Specify additional names that should route to the Cloudfront Distribution.

Note, certificates for these names will not be automatically generated so the certificate option must be specified.

certificateOptional 
public readonly certificate: ICertificate;
  • Type: aws-cdk-lib.aws_certificatemanager.ICertificate

Import the certificate for the domain.

By default, SST will create a certificate with the domain name. The certificate will be created in the us-east-1(N. Virginia) region as required by AWS CloudFront.

Set this option if you have an existing certificate in the us-east-1 region in AWS Certificate Manager you want to use.

domainAliasOptional 
public readonly domainAlias: string;
  • Type: string

An alternative domain to be assigned to the website URL.

Visitors to the alias will be redirected to the main domain. (ie. www.domain.com).

Use this to create a www. version of your domain and redirect visitors to the root domain.

hostedZoneOptional 
public readonly hostedZone: IHostedZone;
  • Type: aws-cdk-lib.aws_route53.IHostedZone

Import the underlying Route 53 hosted zone.

isExternalDomainOptional 
public readonly isExternalDomain: boolean;
  • Type: boolean

Set this option if the domain is not hosted on Amazon Route 53.

NextjsLambdaProps

Initializer 

import { NextjsLambdaProps } from 'cdk-nextjs-standalone'

const nextjsLambdaProps: NextjsLambdaProps = { ... }

Properties

Name Type Description
nextjsPath string Relative path to the directory where the NextJS project is located.
compressionLevel number 0 - no compression, fatest 9 - maximum compression, slowest.
environment {[ key: string ]: string} Custom environment variables to pass to the NextJS build and runtime.
isPlaceholder boolean Skip building app and deploy a placeholder.
nodeEnv string Optional value for NODE_ENV during build and runtime.
quiet boolean Less build output.
tempBuildDir string Directory to store temporary build files in.
nextBuild NextjsBuild Built nextJS application.
function aws-cdk-lib.aws_lambda.FunctionOptions Override function properties.
nextjsPathRequired 
public readonly nextjsPath: string;
  • Type: string

Relative path to the directory where the NextJS project is located.

Can be the root of your project (.) or a subdirectory (packages/web).

compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
  • Default: 1

0 - no compression, fatest 9 - maximum compression, slowest.

environmentOptional 
public readonly environment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Custom environment variables to pass to the NextJS build and runtime.

isPlaceholderOptional 
public readonly isPlaceholder: boolean;
  • Type: boolean

Skip building app and deploy a placeholder.

Useful when using next dev for local development.

nodeEnvOptional 
public readonly nodeEnv: string;
  • Type: string

Optional value for NODE_ENV during build and runtime.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean

Less build output.

tempBuildDirOptional 
public readonly tempBuildDir: string;
  • Type: string

Directory to store temporary build files in.

Defaults to os.tmpdir().

nextBuildRequired 
public readonly nextBuild: NextjsBuild;

Built nextJS application.

functionOptional 
public readonly function: FunctionOptions;
  • Type: aws-cdk-lib.aws_lambda.FunctionOptions

Override function properties.

NextjsLayerProps

Initializer 

import { NextjsLayerProps } from 'cdk-nextjs-standalone'

const nextjsLayerProps: NextjsLayerProps = { ... }

NextjsProps

Initializer 

import { NextjsProps } from 'cdk-nextjs-standalone'

const nextjsProps: NextjsProps = { ... }

Properties

Name Type Description
nextjsPath string Relative path to the directory where the NextJS project is located.
compressionLevel number 0 - no compression, fatest 9 - maximum compression, slowest.
environment {[ key: string ]: string} Custom environment variables to pass to the NextJS build and runtime.
isPlaceholder boolean Skip building app and deploy a placeholder.
nodeEnv string Optional value for NODE_ENV during build and runtime.
quiet boolean Less build output.
tempBuildDir string Directory to store temporary build files in.
cdk NextjsCdkProps Allows you to override default settings this construct uses internally to create the cloudfront distribution.
customDomain string | NextjsDomainProps The customDomain for this website. Supports domains that are hosted either on Route 53 or externally.
stageName string No description.
waitForInvalidation boolean While deploying, waits for the CloudFront cache invalidation process to finish.
nextjsPathRequired 
public readonly nextjsPath: string;
  • Type: string

Relative path to the directory where the NextJS project is located.

Can be the root of your project (.) or a subdirectory (packages/web).

compressionLevelOptional 
public readonly compressionLevel: number;
  • Type: number
  • Default: 1

0 - no compression, fatest 9 - maximum compression, slowest.

environmentOptional 
public readonly environment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Custom environment variables to pass to the NextJS build and runtime.

isPlaceholderOptional 
public readonly isPlaceholder: boolean;
  • Type: boolean

Skip building app and deploy a placeholder.

Useful when using next dev for local development.

nodeEnvOptional 
public readonly nodeEnv: string;
  • Type: string

Optional value for NODE_ENV during build and runtime.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean

Less build output.

tempBuildDirOptional 
public readonly tempBuildDir: string;
  • Type: string

Directory to store temporary build files in.

Defaults to os.tmpdir().

cdkOptional 
public readonly cdk: NextjsCdkProps;

Allows you to override default settings this construct uses internally to create the cloudfront distribution.

customDomainOptional 
public readonly customDomain: string | NextjsDomainProps;

The customDomain for this website. Supports domains that are hosted either on Route 53 or externally.

Note that you can also migrate externally hosted domains to Route 53 by following this guide.

Example

new Nextjs(this, "Web", {
  nextjsPath: ".",
  customDomain: "domain.com",
});

new Nextjs(this, "Web", {
  nextjsPath: "packages/web", // monorepo: relative to the root of the CDK project
  customDomain: {
    domainName: "domain.com",
    domainAlias: "www.domain.com",
    hostedZone: "domain.com"
  },
});
stageNameOptional 
public readonly stageName: string;
  • Type: string
waitForInvalidationOptional 
public readonly waitForInvalidation: boolean;
  • Type: boolean

While deploying, waits for the CloudFront cache invalidation process to finish.

This ensures that the new content will be served once the deploy command finishes. However, this process can sometimes take more than 5 mins. For non-prod environments it might make sense to pass in false. That'll skip waiting for the cache to invalidate and speed up the deploy process.