Next.js on Compute

NOTE: Version 2 is coming soon! It is a substantial update that contains support for additional features:

• Adds support for Next.js 13. New modular design allows us to build support for new versions more easily.
  • Note: The App Router is not yet supported.
• Adds support for React 18's streaming rendering mode.
• A new server layer that simulates Vercel's Middleware / Cache / Functions architecture.
  • Adds support for Edge SSR / Edge API Routes by specifying the edge runtime.
  • Adds support for Edge Middleware.
  • Adds support for Incremental Static Regeneration, with support for On-demand Revalidation and Draft Mode (as well as Preview Mode).

Check it out at https://github.com/fastly/next-compute-js/tree/v2

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

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, 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, run:

npx @fastly/next-compute-js@latest init

This will generate a Compute 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 service) by using the following commands.

Local Development:

cd ./compute-js
fastly compute serve

Deploy to Compute:

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:

npm run fastly-publish

Configuring the Compute application

Being a Compute 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 - (See note below)
• 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 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.9.0 (current)

MDX

It's possible to use MDX by following the directions on this page on the Next.js website: Using MDX with Next.js.

The plugin performs its pre-rendering and compilation of MDX during build time, and for Compute you will need to exclude the @next/mdx plugin itself during runtime:

if (!process.env.NEXT_COMPUTE_JS) {
  // Apply MDX loader only at compile time
  const withMDX = require('@next/mdx')({
    extension: /\.mdx?$/,
    options: {
      remarkPlugins: [],
      rehypePlugins: [],
    },
  });
  module.exports = withMDX({
    ...module.exports,
    // Append the default value with md extensions
    pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
  });
}

Troubleshooting

Error: Cannot find module '@fastly/http-compute-js/dist/polyfill'

You may see the following problem if you have @fastly/[email protected] installed:

[webpack-cli] Error: Cannot find module '@fastly/http-compute-js/dist/polyfill'

If so, you can re-scaffold your compute-js application with v0.7.2 or newer.

Or, you can make the following changes to webpack.config.js:

• Remove these lines

     new webpack.ProvidePlugin({
       Buffer: [ 'buffer', 'Buffer' ],
       process: 'process',
-      setTimeout: [ 'timeout-polyfill', 'setTimeout' ],
-      clearTimeout: [ 'timeout-polyfill', 'clearTimeout' ],
     }),

• Remove these lines

     alias: {
-      'timeout-polyfill': require.resolve('@fastly/http-compute-js/dist/polyfill'),
       'next/dist/compiled/etag': require.resolve('@fastly/next-compute-js/build/src/util/etag'),
       'next/dist/compiled/raw-body': require.resolve('raw-body'),
     },

statics.js not being built correctly?

If you've recently updated the version of Fastly CLI, please check the build scripts defined in fastly.toml and package.json. The currently recommended default values are as follows:

1. fastly.toml

The [scripts.build] should look like this:

[scripts]
build = "npm run build"

2. package.json

The "scripts" should contain the following values:

{
    "prebuild": "npx check-next-version && npx @fastly/compute-js-static-publish --build-static --suppress-framework-warnings && webpack",
    "build": "js-compute-runtime ./bin/index.js ./bin/main.wasm",
    "deploy": "npm run build && fastly compute deploy"
}

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.