Next.js Starter Template

We’re making it easier to host Next.js on AWS with the launch of our Next.js template.

Built for Next.js 13, the template uses the ‘open-next’ framework to prepare your Next.js site for AWS, and defines the required resources using CDK that you can run in your account.

Unlike other approaches to hosting Next.js on AWS, this template is a starting point that leaves you in full control and doesn’t lock you in. The Next.js template scaffolds out a working, deploy ready Next.js project built by the Akeero Diagram to Code platform.

By using Akeero’s Diagram to Code platform you have the ability to extend the base template to add additional resources like API Gateway, Lambda and EventBridge within the same stack. When you’re ready to deploy, export your project to CDK by saving it locally. You’re left with a working CDK project that uses the latest version of the CDK framework, with no custom resources, and no dependencies on Akeero.

Resources

The template is based on the Open Next (https://open-next.js.org/) project, which generates the static assets and required Lambda function code.

It consists of the following resources:

CloudFront Distribution

Lambda Functions

  • Server function: Does the core rendering of the site. When your Next.js site requires custom Environment variables to run you would add them to this Lambda Function
  • Image Optimization Function: Renders optimised images for delivery, using the React Image component

S3 Bucket

  • Cache Bucket: Used to cache rendered pages to avoid re-rendering when possible
  • Assets Bucket: Holds all your static assets

Screenshot of Akeero showing the Next.js template

Pre-Requisites

Once off steps needed to enable you to run CDK scripts to deploy infrastructure in your AWS account.

This can be done just before the first deploy

Getting Started

  1. Bootstrap a Next.js application:
npx create-next-app@latest <app-name> --ts --use-npm
  1. Install Open Next:
cd <app-name>
npm install -D open-next
  1. Run Open Next to generate your function code
npx open-next build
  1. Update your .gitignore file in the generated repository to ignore the .open-next directory
# add the line below to your .gitignore
.open-next
  1. Head to Akeero to generate a project from the Next.js template (Templates > NextJs Template)
  1. You should now be in the Diagram to Code canvas. First up let’s edit the project name
  1. Save the project locally, selecting the root folder of your web app.
  1. Go back to the terminal and install the relevant CDK and Akeero dependencies
cd akeero-cdk
npm install

If you have not bootstrapped CDK for the first time in your AWS account and AWS region, run the following. You only need to bootstrap an account and region once for CDK to work.

npx cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1
  1. Run CDK Deploy
npx cdk deploy

This command will deploy your site!

Once deployed you should get the CloudFront domain of your distribution as an output for the command! At this point you have a live running site.

Updating your project

In the previous steps we created a new Next.js app, used Open Next to build, then used a base template in Akeero to define the AWS infrastructure required to host it. Now lets update the infrastructure to meet the needs of your application.

Let’s head back to Akeero to add a domain name, and update some of the CloudFront behaviours.

Adding a custom domain

Adding a custom domain name is as simple as editing the CloudFront distribution to include a root domain name and a sub domain.

For custom domains, you must have already configured a Hosted Zone in Route53 that corresponds to the Root domain you specify in Akeero.

Creating a public hosted zone - Amazon Route 53

Updating CloudFront Behaviours

With CloudFront we map different routes to different origins using CloudFront behaviours. The default route is the Server Function, requests for images are to the Image Optimization Function, and the rest are to the Assets Bucket. When Open Next prepares your application for hosting on AWS, it copies everything from your Next.js /public directory to an Assets directory that the template copies to S3 for hosting.

The behaviour that maps to /my-images/* is just an example. You can delete that, or update it to map it to something else. You can also add a custom cache policy to it if you know that the assets in there are never going to change, or are going to change regularly.

In this example we’ll add a custom cache policy for 3 assets, and update the name of the /my-images directory to /pdf:

Making changes live

With each of the examples above we’ve updated the infrastructure, but we haven’t pushed it live. To make those changes live, run the command below from your /akeero-cdk folder.

npx cdk deploy --all

You’ll notice we’ve added –all to the cdk deploy command. This is because we’ve add a custom domain, which requires an SSL certificate to be provisioned in its own stack. The –all tells CDK to deploy all stacks defined in the script.

Updating your Next.js App

When you make changes to your Next.js app, it’s as simple as re-running the Open Next build command in your project root, then re-deploying from the /akeero-cdk directory.

npx open-next build
cd akeero-cdk
npx cdk deploy --all

Extending your application

Once you have a running Next.js site hosted in AWS, you can use Akeero to extend functionality like adding EventBridge to enable event driven workflows, or add a database like DynamoDB.

The benefit of using Akeero to extend this base template is that all the resources remain in a single stack, which means they’re deployed and managed together reducing complexity.

Screenshot of Akeero showing an extending AWS infrastructure

Try it out!

Have a go today. If you think it needs more tweaks or think of a way to improve it drop us feedback in the app!

Happy building!