Note: This documentation is for version 1 of the Now platform. For the latest features, please see the version 2 documentation. If you have yet to upgrade, see the upgrade guide.

Building and Deploying a Next.js Application

Next.js is a lightweight framework for creating static and server-rendered applications, which abstracts away all of the complicated parts required for creating a React application.

To start, create a directory for the Next.js application to go into:

mkdir next-app && cd next-app

In order to use Next.js, we need to install Next itself, React, and ReactDOM:

yarn add next react react-dom

Installing next, react, and react-dom using Yarn.

Alternatively, use npm to install these packages by using npm install next react react-dom --save.

Next, create the project's package.json in that directory:

{
  "name": "next-app",
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}

The name and scripts content of a basic Next.js application within a package.json file.

Alternatively, you can statically export a Next.js application by using an additional script within the "scripts" section:

"export": "next export"

Now that the project's meta files are in place, code can be added that will be rendered when a visitor accesses the site.

With most frameworks, you would now have to set up a router and tell it about the page you would like to add. With Next.js, the only thing to do is create a page, and the framework will automatically handle the rest.

In turn, the next step will be to add a directory named "pages". As the name indicates, this is where all pages of your application will be located. Based on the directory structure, each file will be mounted on a specific path.

For example, add an index.js file inside the "pages" directory, which will be served when the / path is accessed on the app. Similarly, about.js will route to /about.

Into the index.js file, place the following code:

export default () => (
  <p>Welcome to Next.js!</p>
)

The above code is exporting JSX which renders a paragraph with text content inside of it.

Next.js is now ready to serve content.

Next.js comes with an excellent development toolchain built-in. We've defined one of these commands earlier in the package.json file we've created: The dev script (linked to the next command), which can be can run like this:

npm run dev

When running the command, Next.js will build the code and serve it on the address shown in the terminal. Also, it will watch for changes on the files inside your project. If you make changes to the code, the app will be built again.

This is how it should look:

You can now go to http://localhost:3000 in your browser and see the rendered markup:

Now the application is ready to be deployed.

For more information on Next.js, visit the website and the documentation.

There are two methods for deploying a Next.js application due to the ability of Next being able to both render server-side and statically at build-time.

For statically exported Next.js applications using next export in the package.json scripts, as noted in the Getting Started portion of this example guide, Now supports the static export by default.

Static Builds on Now allow Next.js apps to be built and deployed all with one command.

To build the app when deploying, first set the type of deployment to static within a now.json configuration file:

{
  "type": "static"
}

With the deployment type set as static, a Dockerfile can be created and Now will detect the Dockerfile and take the instructions within as the build steps.

Using a Node base image, the Dockerfile can use the scripts within the package.json to build and export the Next.js app statically into the public directory, which is where Now will use to serve the content from.

# Using lightweight Node.js base with Yarn to install our dependencies and build and export the app
FROM mhart/alpine-node:10

# Set the working directory and copy over package manager specific files
WORKDIR /usr/src
COPY package.json yarn.lock ./

# Install dependencies
RUN yarn

# Copy the rest of the app files to the working directory
COPY . .

# Build the app and export the static files to the `public` directory
RUN yarn build && yarn export -o /public

A Dockerfile containing the build instructions for a static Next.js application.

Additionally, create a .dockerignore file to whitelist the files needed to avoid deploying anything unnecessary:

*
!pages
!components
!package.json
!yarn.lock

A .dockerignore file whitelisting necessary directories and files for deployment.

With the configuration set and the build instructions defined, the app is ready to be deployed and built with just one command:

now

The app will be then built and deployed with Now, providing you with a deployment link to share or to alias for staging or to push live.

View the example application on the zeit/now-examples repository.

To deploy a server-rendered Next.js application, all that's needed is to set the deployment type and create instructions for how Now can run the app within the deployment.

Set the deployment type to docker and enable Now Cloud v2 within a now.json file:

{
  "type": "docker",
  "features": {
    "cloud": "v2"
  }
}

Then, create a Dockerfile with the instructions to prepare and start the server that will render the Next.js application:

# Use a Node.js image and assign it as our build
FROM mhart/alpine-node:10 as build

# Set the working directory, copy dependency management files to the working directory,
# and install the dependencies
WORKDIR /usr/src
COPY package.json yarn.lock ./
RUN yarn install

# Copy all files to the working directly, build the application
# and purge the development dependencies
COPY . .
RUN yarn build && yarn --production

# Create a new image using a minimal Node.js image
# with no extra tools packaged in, such as Yarn or npm for the smallest final size
FROM mhart/alpine-node:base-10

# Set the working directory for the new image and
# set the `NODE_ENV` environment variable value to `production`
# along with setting the path for node_modules to be accessible
WORKDIR /usr/src
ENV NODE_ENV="production"
ENV PATH="./node_modules/.bin:$PATH"

# Copy files from the base image over to our new image's working directory
COPY --from=build /usr/src .

# Start the server for Next.js using Node.js
CMD ["next", "start"]

A Dockerfile utilizing multi-stage builds to produce a minimal final image which, in combination with Now Cloud v2, helps with fast cold-boot times and performance.

Additionally, with a .dockerignore file, we avoid deploying any unnecessary files:

*
!pages
!components
!package.json
!yarn.lock

Finally, all that is left to do is deploy:

now

With that, your app will be built and ran with Now, which will give you the resulting deployment link to share and push live.

View the example application on the zeit/now-examples repository.