Static Build (@now/static-build)

This module takes a Node.js package.json file, installs all its dependencies, executes the now-build step and exposes the resulting dist directory as the build output for serving.

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 on a developer machine or CI, you want Now to do it in the cloud every time you deploy.

Note: At the moment, `@now/static-build` only supports build processes that can be expressed using Node.js and npm dependencies.

How to use it

First, decide on a directory where your statically generated site source code will reside. This can be the top level directory or a sub-directory inside a monorepo.

In this example, we will use @now/static-build to build two Hugo websites statically.

mkdir my-appcd my-app

Install hugo so that you can use its bootstrapping tools, and run:

hugo new site docshugo new site blog

Go inside each directory and create a package.json file. We can use yarn to bootstrap it and also include hugo so that Now can build it:

yarn add hugo-cli

Hugo requires that you download and configure a theme. For this example we ran inside docs and blog:

git init;\
git submodule add themes/ananke;\
echo 'theme = "ananke"' >> config.toml

And create an example post in both docs and blog:

hugo new posts/

Make sure node_modules and dist are in .nowignore


Finally, for Now to know what to execute, add to package.json:

"scripts": {
  "now-build": "hugo -d dist"

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

Finally, we tell Now that we want to execute two builds for this deployment:

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

Technical Details


The src of each build you define with @now/static must be a package.json file.

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.

Node.js version

The Node.js version used is the latest in the 8 branch.