Static Builds Builder (@now/static-build)

Status: Stable

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.

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.

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, or the directory defined as the value of the config option distDir.

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" }

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" } }

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

The installation algorithm of dependencies works as follows:

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

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

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