Status: Stable

The Now Next.js Builder takes a Next.js application, defined by a next.config.js entrypoint and pages directory, and converts those pages into a series of individual lambdas.

It features built-in caching of node_modules and all compiler artifacts for very fast deployments.

When to Use It

@now/next is the ideal way to ship a fast, production-ready Next.js application that scales automatically.

For more information on why you should use Next.js for your project, see the Next.js website.

How to Use It

The first step is to set up a Next.js project. If you have not yet done so; the best place to get started is the Next.js documentation.

To get started, make sure you have installed the Next.js dependencies with the following command:

yarn add next react react-dom

Then, in your project directory, create a pages directory with some example pages, for example; the home index page, pages/index.js:

export default () => <div>Hello world!</div>

Create a simple next.config.js file to use as our entrypoint for the build, and to configure that the build should be a collection of serverless lambdas:

module.exports = {
  target: 'serverless'
}
Note: The serverless method is only supported in Next.js version 8 and above.

Then define a build step in a now.json configuration file:

{
  "version": 2,
  "builds": [{ "src": "next.config.js", "use": "@now/next" }]
}

To prevent unintended issues and to speed up the uploading step of the deployment process, make sure to add both the .next and node_modules directories to a .nowignore file.

Upon deployment, you will get a URL like the following: https://nextjs-8fnzfb1ci.now.sh

Also, the source code of the deployment can be checked by appending /_src e.g. https://nextjs-8fnzfb1ci.now.sh/_src.

For a more in-depth guide on setting up and deploying Next.js with caching headers, see our guide:

If you are looking to set up custom routes for your Next.js app, see the following guide:

Technical Details

Entrypoint

The entrypoint of this builder is a next.config.js file with the target configuration option set to serverless.

module.exports = {
  target: "serverless"
}

This configuration, shown above, tells Next.js to build each page in the pages directory as a lambda function.

For more information on this, see the Next.js documentation.

Dependencies installation

The installation algorithm of dependencies works as follows:

  • If a package-lock.json is present, npm install is used
  • Otherwise, yarn is used.

Private npm modules

To install private npm modules, define NPM_TOKEN as a build environment in now.json.

Build Step

You can run build tasks by creating a now-build script within a package.json file. If no now-build script is defined, then next build is assumed. If now-build is defined, it will replace next build.

An example package.json with a now-build script:
{
  "scripts": {
    "now-build": "node build.js && next build"
  }
}
An example build script, named build.js:
const fs = require('fs');
const path = require('path');
const filename = path.join('pages', 'time.js');
const contents = `module.exports = "${new Date().toISOString()}"`;
fs.writeFile(filename, contents, (err) => {
  if (err) throw err
  console.log('time.js file created successfully!')
});
To tie it all together, add a now.json file:
{
  "version": 2,
  "builds": [
    { "src": "package.json", "use": "@now/next" }
  ]
}

The resulting Lambda contains the build time: https://nextjs-build-pqo9ri0y2.now.sh/

Node.js version

The Node.js version used is the v8.10.

Custom Server

This builder separates your pages into individual serverless endpoints, so you cannot use a custom server.

Using a custom server would require that all pages be routed through that custom server and the application would lose out on many of the benefits of serverless Next.js. You can still achieve most of the logic that you have in a custom server by using getInitialProps() and using routes.

Maximum Lambda Bundle Size

To help keep cold boot times low, the maximum output bundle size for a Next.js output lambda is, by default, 5mb. This limit is extendable up to 50mb.

Example maxLambdaSize configuration:
{
  "builds": [
    { "src": "next.config.js", "use": "@now/next", "config": { "maxLambdaSize": "10mb" } }
  ]
}