Static Builds Builder (@now/static-build)

This Builder exposes a dist directory built from either of two methods:

• Using a package.json file, the Builder installs its dependencies and executes the now-build script within, expecting a dist directory as the build output.
• Using a shell file, the Builder executes each of the instructions within, expecting an output of a dist directory as the build output.

The default expectation of the dist directory as the build output can be configured to be another directory.

When to Use It

This Builder is very useful when you have source files that when built will be served statically, but instead of pre-building yourself locally, or in a CI, Now will build it in the cloud every time you deploy.

How to Use It

First, create a project directory where your source code will reside. This can be the root directory for your project or a sub-directory inside of a monorepo.

In this example, we will show you how to use @now/static-build to build a Next.js project statically and deploy it, with one command.

The following example will focus on configuring Now to deploy an existing project.

See the Local Development section for more information on using this builder using now dev.

Static Builder Configuration for Next.js

Next.js uses npm dependencies, so to ensure a fresh build for each deployment, make sure both node_modules and dist are in the .nowignore file:

node_modules
dist

Contents of a .nowignore file that prevents the node_modules and dist directories from uploading.

Finally, for Now to know what to execute, extend the scripts object in your package.json with the following now-build property:

{
  ...
  "scripts": {
    ...
    "now-build": "next build && next export -o dist"
  }
}

An extended scripts object containing a now-build script with build instructions.

Notice that @now/static-build:

• Uses package.json as a way of getting dependencies and specifying your build.
• Will only execute your now-build script.
• Expects the output to go to dist, or the directory defined as the value of the config option distDir.

Finally, tell Now that you want to execute a build for this deployment by creating a now.json file with the following contents:

{
  "version": 2,
  "builds": [{ "src": "package.json", "use": "@now/static-build" }]
}

A now.json file defining the Now platform version and a build step using the @now/static-build Builder.

Deployment

With the Builder configured in your project, you can deploy your project with Now whenever you update your code and it will be built fresh each time.

Once deployed, you will receive a URL of your built project similar to the following: https://static-next-btz2x20cw.now.sh/

The example deployment above is open-source and you can view the code for it here: https://static-next-btz2x20cw.now.sh/_src

Configuring the Build Output Directory

If you want to configure a directory other than dist for your build output, you can pass an optional distDir option in the builder's config:

{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@now/static-build",
      "config": { "distDir": "www" }
    }
  ]
}

Monorepo Usage

The @now/static-build Builder can be used for multiple build steps in the same project. To build two Next.js websites, for example one in the root of the project and another in the docs directory, the following configuration would be used in a now.json file:

{
  "version": 2,
  "builds": [
    { "src": "package.json", "use": "@now/static-build" },
    { "src": "docs/package.json", "use": "@now/static-build" }
  ]
}

Local Development

With the@now/static-build Builder, you are able to define a custom script that runs specified functionality along with the serverless replication that now dev provides.

To do this, you can provide a now-dev script within a package.json file that defines the behavior of the now dev command. Doing so will not affect the functionality that the command provides, including mimicking the serverless environment locally.

For example, if you would like to develop a Gatsby site locally, using a now.json file such as the following:

{
  "version": 2,
  "builds": [{ "src": "package.json", "use": "@now/static-build" }]
}

Your package.json file can define a now-dev script that uses the Gatsby CLI to run a development environment locally:

{
  ...
  "scripts": {
    ...
    "now-dev": "gatsby develop -p $PORT"
  }
}

As you can see with the above example, we also pass a $PORT variable to the command. now dev will automatically pass the port it's looking to use with the $PORT variable for you to use in your custom scripts, so the command can attach the extended behaviour to the environment.

Technical Details

Entry Point

The src value of each build step that uses the @now/static-build Builder can be either a package.json file with a now-build script or a shell file.

package.json Entry Point

The package.json entry point must contain a script within a scripts property called now-build. The value of this script must contain the instructions for how Now should build the project, with the result of the build's final output in the dist directory (unless configured).

For example, building a statically exported Next.js project:

{
  ...
  "scripts": {
    "now-build": "next build && next export -o dist"
  }
}

An example scripts property in a package.json file used to statically build an export Next.js.

This file accompanies a now.json file with a build step that points to the package.json file as an entry point:

{
  "version": 2,
  "builds": [{ "src": "package.json", "use": "@now/static-build" }]
}

An example now.json file that uses the above package.json file as an entry point.

Shell File Entry Point

Using a file with a .sh file extension as an entry point for the @now/static-build Builder allows you to define build instructions in a shell file.

For example, creating a shell file, with the name build.sh, with the following contents will install and build a Hugo project:

curl -L -O https://github.com/gohugoio/hugo/releases/download/v0.55.6/hugo_0.55.6_Linux-64bit.tar.gz
tar -xzf hugo_0.55.6_Linux-64bit.tar.gz

./hugo

Example shell file that installs and builds a Hugo project.

The build.sh file accompanies a now.json file with a build step that points to the build.sh file as an entry point:

{
  "version": 2,
  "builds": [
    {
      "src": "build.sh",
      "use": "@now/static-build",
      "config": { "distDir": "public" }
    }
  ]
}

By default, Hugo builds to the public directory, so the config property contains an extra distDir option that sets the output directory for Now to look in after the build instructions of the build.sh file are finished.

Now will look for the dist directory by default.

Dependencies Installation

The installation algorithm of dependencies works as follows:

For package.json Entry Points

If a package.json is used as an entry point, the following behavior applies for dependencies listed inside of it:

• If a package-lock.json is present in the project, npm install is used.
• Otherwise, yarn is used, by default.

For Shell Entry Points

yum is fully available to install any dependencies from within a shell entry point file.

For example, installing wget from a shell entry point and using it to install Hugo, then unpacking Hugo with tar, which is built-in:

yum install -y wget

wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz

tar -xzf hugo_0.31.1_Linux-64bit.tar.gz

Private npm Modules

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

Alternatively, define NPM_RC as a build environment variable with the contents of ~/.npmrc.

Node.js Version

The default Node.js version used is 8.10.x.

The version can be changed to 10.x by defining engines in package.json.

Resources

The goal of the ZEIT Docs is to provide you with all the information you need to easily deploy your projects. The following resources are related to this document, and can help you with your goals: