Nextjs
Reference doc for the `sst.aws.Nextjs` component.
The Nextjs
component lets you deploy Next.js apps on AWS. It uses
OpenNext to build your Next.js app, and transforms the build
output to a format that can be deployed to AWS.
Minimal example
Deploy the Next.js app that’s in the project root.
Change the path
Deploys a Next.js app in the my-next-app/
directory.
Add a custom domain
Set a custom domain for your Next.js app.
Redirect www to apex domain
Redirect www.my-app.com
to my-app.com
.
Link resources
Link resources to your Next.js app. This will grant permissions to the resources and allow you to access it in your app.
You can use the SDK to access the linked resources in your Next.js app.
Constructor
Parameters
-
name
string
-
args?
NextjsArgs
-
opts?
ComponentResourceOptions
NextjsArgs
assets?
Type Input
<
Object
>
Default Object
Configure how the Next.js app assets are uploaded to S3.
By default, this is set to the following. Read more about these options below.
Read more about these options below.
assets.fileOptions?
Type Input
<
Object
[]
>
Specify the Content-Type
and Cache-Control
headers for specific files. This allows
you to override the default behavior for specific files using glob patterns.
Apply Cache-Control
and Content-Type
to all zip files.
Apply Cache-Control
to all CSS and JS files except for CSS files with index-
prefix in the main/
directory.
assets.fileOptions[].cacheControl?
Type string
The Cache-Control
header to apply to the matched files.
assets.fileOptions[].contentType?
Type string
The Content-Type
header to apply to the matched files.
assets.fileOptions[].files
Type string
|
string
[]
A glob pattern or array of glob patterns of files to apply these options to.
assets.fileOptions[].ignore?
Type string
|
string
[]
A glob pattern or array of glob patterns of files to exclude from the ones matched
by the files
glob pattern.
assets.nonVersionedFilesCacheHeader?
Type Input
<
string
>
Default “public,max-age=0,s-maxage=86400,stale-while-revalidate=8640”
The Cache-Control
header used for non-versioned files, like index.html
. This is used by both CloudFront and the browser cache.
The default is set to not cache on browsers, and cache for 1 day on CloudFront.
assets.textEncoding?
Type Input
<
“
none
”
|
“
ascii
”
|
“
utf-8
”
|
“
iso-8859-1
”
|
“
windows-1252
”
>
Default “utf-8”
Character encoding for text based assets, like HTML, CSS, JS. This is
used to set the Content-Type
header when these files are served out.
If set to "none"
, then no charset will be returned in header.
assets.versionedFilesCacheHeader?
Type Input
<
string
>
Default “public,max-age=31536000,immutable”
The Cache-Control
header used for versioned files, like main-1234.css
. This is
used by both CloudFront and the browser cache.
The default max-age
is set to 1 year.
buildCommand?
Type Input
<
string
>
Default “npx —yes open-next@OPEN_NEXT_VERSION build”
The command used internally to build your Next.js app. It uses OpenNext with the openNextVersion
.
If you want to use a custom build
script from your package.json
.
domain?
Type Input
<
string
|
Object
>
Set a custom domain for your Next.js app.
Automatically manages domains hosted on AWS Route 53, Cloudflare, and Vercel. For other
providers, you’ll need to pass in a cert
that validates domain ownership and add the
DNS records.
By default this assumes the domain is hosted on Route 53.
For domains hosted on Cloudflare.
Specify a www.
version of the custom domain.
domain.aliases?
Type Input
<
string
[]
>
Alias domains that should be used. Unlike the redirect
option, this keeps your visitors
on this alias domain.
So if your users visit app2.domain.com
, they will stay on app2.domain.com
in their
browser.
domain.cert?
Type Input
<
string
>
The ARN of an ACM (AWS Certificate Manager) certificate that proves ownership of the domain. By default, a certificate is created and validated automatically.
The certificate will be created in the us-east-1
region as required by AWS CloudFront.
If you are creating your own certificate, you must also create it in us-east-1
.
To manually set up a domain on an unsupported provider, you’ll need to:
- Validate that you own the domain by creating an ACM certificate. You can either validate it by setting a DNS record or by verifying an email sent to the domain owner.
- Once validated, set the certificate ARN as the
cert
and setdns
tofalse
. - Add the DNS records in your provider to point to the CloudFront distribution URL.
domain.dns?
Type Input
<
false
|
sst.aws.dns
|
sst.cloudflare.dns
|
sst.vercel.dns
>
Default sst.aws.dns
The DNS provider to use for the domain. Defaults to the AWS.
Takes an adapter that can create the DNS records on the provider. This can automate validating the domain and setting up the DNS routing.
Supports Route 53, Cloudflare, and Vercel adapters. For other providers, you’ll need
to set dns
to false
and pass in a certificate validating ownership via cert
.
Specify the hosted zone ID for the Route 53 domain.
Use a domain hosted on Cloudflare, needs the Cloudflare provider.
Use a domain hosted on Vercel, needs the Vercel provider.
domain.name
Type Input
<
string
>
The custom domain you want to use.
Can also include subdomains based on the current stage.
domain.redirects?
Type Input
<
string
[]
>
Alternate domains to be used. Visitors to the alternate domains will be redirected to the
main name
.
Use this to create a www.
version of your domain and redirect visitors to the apex domain.
environment?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Set environment variables in your Next.js app. These are made available:
- In
next build
, they are loaded intoprocess.env
. - Locally while running
sst dev next dev
.
Recall that in Next.js, you need to prefix your environment variables with NEXT_PUBLIC_
to access these in the browser. Read more here.
imageOptimization?
Type Object
Default {memory: “1024 MB”}
Configure the Lambda function used for image optimization.
imageOptimization.memory?
Type “
${number} MB
”
|
“
${number} GB
”
Default “1024 MB”
The amount of memory allocated to the image optimization function. Takes values between 128 MB and 10240 MB in 1 MB increments.
imageOptimization.staticEtag?
Type boolean
Default false
If set to true, already computed image will return 304 Not Modified. This means that image needs to be immutable, the etag will be computed based on the image href, format and width and the next BUILD_ID.
Wait for all paths to be invalidated.
invalidation.paths?
Type Input
<
string
[]
|
“
all
”
|
“
versioned
”
>
Default “all”
The paths to invalidate.
You can either pass in an array of glob patterns to invalidate specific files. Or you can use one of these built-in options:
all
: All files will be invalidated when any file changesversioned
: Only versioned files will be invalidated when versioned files change
Invalidate the index.html
and all files under the products/
route. This counts as two invalidations.
invalidation.wait?
Type Input
<
boolean
>
Default false
Configure if sst deploy
should wait for the CloudFront cache invalidation to finish.
Waiting for this process to finish ensures that new content will be available after the deploy finishes. However, this process can sometimes take more than 5 mins.
link?
Type Input
<
any
[]
>
Link resources to your Next.js app. This will:
- Grant the permissions needed to access the resources.
- Allow you to access it in your site using the SDK.
Takes a list of resources to link to the function.
openNextVersion?
Type Input
<
string
>
Default The latest version of OpenNext
Configure the OpenNext version used to build the Next.js app.
By default, this is pinned to the version of OpenNext that was released with the SST version you are using. You can find this in the source under DEFAULT_OPEN_NEXT_VERSION
.
path?
Type Input
<
string
>
Default ”.”
Path to the directory where your Next.js app is located. This path is relative to your sst.config.ts
.
By default this assumes your Next.js app is in the root of your SST app.
If your Next.js app is in a package in your monorepo.
permissions?
Type Input
<
Object
[]
>
Permissions and the resources that the server function in your Next.js app needs to access. These permissions are used to create the function’s IAM role.
Allow reading and writing to an S3 bucket called my-bucket
.
Perform all actions on an S3 bucket called my-bucket
.
Grant permissions to access all resources.
permissions[].actions
Type string
[]
The IAM actions that can be performed.
permissions[].resources
Type Input
<
string
>
[]
The resourcess specified using the IAM ARN format.
transform?
transform.assets?
Type BucketArgs
|
(
args
:
BucketArgs
=>
void
)
Transform the Bucket resource used for uploading the assets.
transform.cdn?
transform.server?
Type FunctionArgs
|
(
args
:
FunctionArgs
=>
void
)
Transform the server Function resource.
vpc?
Type Input
<
Object
>
Configure the server function in your Next.js app to connect to private subnets in a virtual private cloud or VPC. This allows your app to access private resources.
vpc.securityGroups
Type Input
<
Input
<
string
>
[]
>
A list of VPC security group IDs.
vpc.subnets
Type Input
<
Input
<
string
>
[]
>
A list of VPC subnet IDs.
warm?
Type Input
<
number
>
Default 0
The number of instances of the server function to keep warm. This is useful for cases where you are experiencing long cold starts. The default is to not keep any instances warm.
This works by starting a serverless cron job to make n concurrent requests to the server function every few minutes. Where n is the number of instances to keep warm.
Properties
nodes
nodes.assets
Type Bucket
The Amazon S3 Bucket that stores the assets.
nodes.cdn
Type Output
<
Cdn
>
The Amazon CloudFront CDN that serves the app.
nodes.server
Type Output
<
Function
>
The AWS Lambda server function that renders the app.
url
Type Output
<
string
>
The URL of the Next.js app.
If the domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated CloudFront URL.
SDK
The following are accessible through the SDK at runtime.
Links
The URL of the Next.js app.url
string
If the domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated CloudFront URL.