Next.js on Compute@Edge

Deploy and serve your Next.js website from Fastly's blazing-fast Compute@Edge.

Next.js

Next.js is a popular JavaScript-based server framework that gives the developer a great experience – the ability to write in React for the frontend, and a convenient and intuitive way to set up some of the best features you need for production: hybrid static & server rendering, smart bundling, route prefetching, and more, with very little configuration needed.

Usage

Use create-next-app (or any alternative method) to set up your Next.js app.

Build your site normally as you would in Next.js, and use its built-in development server during development:

npm run dev

When you're ready to deploy your site to Compute@Edge, build your site with the standard build tool:

npm run build

This creates an optimized build of your application and places the output into the ./.next directory, that contains all the files generated from your sources.

To run this in Compute@Edge, run:

npx @fastly/next-compute-js init

This will generate a Compute@Edge project for you and place it in a directory called ./compute-js.

This program can then be served (local development server) or published (to a Compute@Edge service) by using the following commands.

Local Development:

cd ./compute-js
fastly compute serve

Deploy to Compute@Edge:

cd ./compute-js
fastly compute publish

Remember that if you ever change your source files, you will have to run npm run build again to update the built files in your .next directory.

Scripts

In order to simplify the process of building and running or publishing your project, we recommend that you add the following scripts to your package.json file.

{
  "scripts": {
    "fastly-serve": "next build && cd compute-js && fastly compute serve --verbose",
    "fastly-publish": "next build && cd compute-js && fastly compute publish --verbose"
  }
}

Now, you can use the following commands to build, and then run or publish your project:

Local Development:

npm run fastly-serve

Deploy to Compute@Edge:

npm run fastly-publish

Configuring the Compute@Edge application

Being a Compute@Edge JavaScript application, the generated project contains a fastly.toml file. Before publishing your project, you may want to update the various fields to specify your project name, the author name, and the service ID.

Additionally, if the Server-Side parts of your application need any access to backends while running on the local development server, define them here.

Supported Next.js Features

The following Next.js features are supported:

• Static File Routing
• Static Routed Pages - index routes, nested routes
• Dynamic Routed Pages - dynamic route segments, catch-all, optional catch-all
• Link object
• Router object / Imperative Routing / Shallow Routing
• Static Generation without Data
• Server-Side Generation with Static Props / Static Paths
• Server-Side Rendering with Server-Side Props
• Client-Side fetching
• SWR
• Built-in CSS / CSS Modules
• Compression (gzip)
• ETag generation
• Rewrites
• Redirects
• Internationalized Routing
• Layouts
• Font Optimization
• Headers
• MDX
• Custom App
• Custom Document
• Custom Error Page
• API Routes / Middleware

The following features are not yet supported, but are on the radar:

• Image Optimization
• Preview Mode

The following features are not supported at the current time:

• Edge API Routes / Middleware
• Incremental Static Regeneration
• Dynamic Import

API Routes / Middleware

We support API Routes and Middleware. The handlers in your application will receive Node.js-style request and response objects that have Next.js Request and Response helpers applied to them.

At the current time, Edge API Routes and Middleware are not supported.

How it works

Internally this is a custom implementation of the NextServer class provided by Next.js. This implementation uses @fastly/compute-js-static-publish to load up the files from the filesystem under the ./.next directory generated by next build.

Developing

The following lists the directory structure of the tool and the library.

src/
  bin/          - entry point for the CLI
  cli/          - The CLI wrapper for the scaffolding tool
  init-server/  - The main code for the scaffolding tool

  index.ts      - The main library export of this library
  server/       - The code of the Next.js server implementation
  types/        - TypeScript types
  util/         - Util functions
  core/         - Compute@Edge core libraries

test/           - Unit tests (in progress)

examples/       - Examples
resources/      - Files in this directory are copied into the output project by the scaffolding tool   

Next.js Versions

Next.js is under active development, and it makes fairly frequent updates to its internals. Sometimes those changes cause incompatibilities with the current version of next-compute-js.

While newer versions of Next.js may work, this version of next-compute-js supports Next.js 12.3.0.

See the following table for compatibility:

Next.js version	@fastly/next-compute-js version
12.2.2	0.1.1-beta.4
12.2.4	0.2.5
12.2.5	0.2.5
12.3.0	0.3.1 (current)

Issues

If you encounter any non-security-related bug or unexpected behavior, please file an issue using the bug report template.

Security issues

Please see our SECURITY.md for guidance on reporting security-related issues.

License

MIT.