OpenNext is an open-source toolkit that makes it easy to deploy Next.js applications to AWS using modern serverless infrastructure. This guide will walk you through setting up OpenNext, configuring environment variables, and deploying your app to AWS using SST (Serverless Stack).
Why Not Vercel?
Vercel is the default hosting platform for Next.js, offering a seamless developer experience and automatic scaling. However, there are several reasons you might want to deploy your Next.js app on AWS using OpenNext and SST instead:
- Cost Control: AWS can be more cost-effective for high-traffic or enterprise workloads, especially as your app scales.
- Vendor Neutrality: Avoid lock-in to a single provider and use AWS services directly.
- Flexibility: Full control over AWS resources, networking, and integrations.
- Enterprise Requirements: Some organizations require direct AWS hosting for compliance, security, or procurement reasons.
- Custom Infrastructure: Integrate with other AWS services (S3, Lambda, RDS, etc.) natively.
- Rising Costs and Billing Surprises: Vercel and other serverless platforms have been known to unexpectedly increase costs or issue surprise bills, especially for bandwidth or traffic spikes. See real-world stories at Serverless Horrors.
Cons:
- More setup and configuration required compared to Vercel.
- You manage your own AWS account, billing, and IAM.
- Fewer "one-click" features (but more flexibility).
OpenNext and SST make AWS deployment much easier, bringing many of the benefits of Vercel to your own AWS account.
Prerequisites
Before you begin, make sure you have:
- An AWS account (https://aws.amazon.com/)
- Node.js (v18 or later recommended)
- npm (https://www.npmjs.com/) or yarn (https://yarnpkg.com/)
- AWS CLI (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed
- SST CLI (https://docs.sst.dev/)
After installing the AWS CLI, configure your credentials:
aws configure
Step 1: Install OpenNext in Your Existing Project
If you already have a Next.js project set up, you can add OpenNext as a dependency using your preferred package manager:
npm install open-next
or
pnpm add open-next
This will install OpenNext in your existing project so you can proceed with AWS deployment.
Project structure overview:
- app/ or pages/: Your Next.js application code
- sst.config.ts: SST configuration file for AWS deployment
- .env.production: Environment variables for production
Step 2: Set Up Environment Variables
Environment variables are essential for configuring your app for different environments (development, production, etc.).
Create a .env.production file in your project root:
SITE_URL=https://example.com
What does this variable do?
- SITE_URL: The base URL of your deployed site.
Never commit secrets to your repository! Add .env.production to your .gitignore:
.env.production
Step 3: Configure sst.config.ts for Environment Variables
Here is an example sst.config.ts configuration:
// sst.config.tsexport default $config({app(input) {return {name: 'my-next-app',removal: input?.stage === 'production' ? 'retain' : 'remove',protect: ['production'].includes(input?.stage),home: 'aws',}},async run() {const SITE_URL = new sst.Secret('SITE_URL')const bucket = new sst.aws.Bucket('MyNextAppBucket', {access: 'public',})const _myWebApp = new sst.aws.Nextjs('MyNextApp', {link: [SITE_URL, bucket],domain: {name: 'example.com',redirects: ['www.example.com'],},})},})
In this configuration, an S3 bucket is created using sst.aws.Bucket. This bucket is used to store and serve static assets for your Next.js app, such as images, CSS, and JavaScript files. By linking the bucket to your Next.js app, SST ensures that your static files are uploaded to S3 and served efficiently via AWS infrastructure. This is a key part of deploying a performant, production-ready Next.js application on AWS.
How it works:
- sst.Secret('SITE_URL') tells SST to look for the variable in your environment and inject it securely into your AWS resources.
- The link array connects this secret and the S3 bucket to your Next.js app.
Step 4: Deploy to AWS
Deploy your app:
npx sst deploy --stage production
What happens during deployment?
- SST provisions AWS resources (Lambda, S3, etc.)
- Your Next.js app is built and uploaded
- Environment variables are injected securely
Step 4.5: Set Up Your Domain with Route 53
To use your custom domain (like example.com) with your AWS deployment, you need to configure DNS using AWS Route 53. Route 53 is Amazon's scalable domain name system (DNS) web service.
Steps:
-
Register or import your domain. You can register a new domain directly in Route 53, or import an existing domain by creating a hosted zone for it.
-
Create a hosted zone. In the Route 53 console, create a public hosted zone for your domain (e.g., example.com).
-
Update your domain's nameservers. If your domain is registered elsewhere, update its nameserver (NS) records to the ones provided by Route 53.
-
Add DNS records for your app. After deploying with SST, you will get a CloudFront distribution domain (e.g., d1234.cloudfront.net). In Route 53, add an A or CNAME record for your domain (and www subdomain if needed) pointing to the CloudFront domain.
Why Route 53?
Route 53 provides reliable, low-latency DNS resolution and integrates seamlessly with other AWS services. Using Route 53 ensures your custom domain points to your AWS-hosted Next.js app with minimal hassle and maximum reliability.
Step 5: Verify Your Deployment
To verify your deployment visit the domain you configured (for example, https://example.com).
Check the AWS Console for your resources.
To view logs and debug, use:
npx sst console
Troubleshooting
-
If you see missing environment variable errors, make sure all required variables are set in your .env.production file and are available in your deployment environment.
-
For AWS permissions errors, ensure your AWS CLI user has sufficient permissions.
-
If you encounter build errors, check your Next.js code and dependencies.
-
If your domain is not working, double-check your DNS and domain configuration in your sst.config.ts and Route 53 settings.
Congrats! You've now deployed Next.js on AWS using OpenNext and SST! For more details, check out the OpenNext documentation (https://opennext.dev/) and SST documentation (https://docs.sst.dev/). If you need help with deployment, get in touch with us.