Builders are modules that transform your source code into the outputs, being either static files and/or lambdas, which are served by our CDN at the edge.

When to Use Builders

If your project has source files that require transformation to be served to users, Builders enable this ability when deploying.

Whether HTML files need to be minified, or dynamic content such as a Node, PHP, Go, or any app using a backend language, need to be deployed, Builders offer the flexibility and availability needed to reach that goal.

How to Use Builders

Builders can be used with Now by creating a now.json file in a project and then using a builds property within that configuration:

{
  "builds": [
    { "src": "*.html", "use": "@now/static" },
    { "src": "date.js", "use": "@now/node" }
  ]
}

The builds property is an array of objects where each object is a build step, including a src and a use property, at least.

The Builder will receive a list of files based on the src property's glob value.

Note: It is important to remember that the src property is a glob. In the above example, this will only use @now/static for the HTML files in the root directory. If you need it to be used throughout subdirectories, you need the appropriate glob syntax: **/*.html.

Builder Versioning

Official Builders are published to npmjs.com and installed at build time. The use statement in your now.json file uses a similar syntax to npm install or yarn add. This means versioning works the same for Builders as it does for any npm package.

The following are valid examples you can use to pin a version of @now/node in your now.json configuration file.

  • @now/node
  • @now/node@latest
  • @now/node@0.7.3
  • @now/node@canary
  • @now/node@0.7.2-canary.2

All Official Builders have a Stable branch and a Canary branch that are published to npm as latest and canary "dist-tags" respectively. Features and fixes will be published to Canary before they reach Stable. If you do not specify a specific version or dist-tag, then the latest version is assumed.

Developing your Own Builder

Extending the feature-set of a Now deployment is as simple as creating a Builder that, as previously mentioned, takes a list of files and outputs either static files or dynamic Lambdas.

A full API reference is available to help with creating Builders.

Technical Details

Caching Data

A builder can retain an archive of up to 100mb of the filesystem at build time. The cache key is generated as a combination of:

  • Deployment name (i.e., the app name)
  • Team id or user id
  • Entrypoint path (e.g., api/users/index.go)
  • Builder identifier including version (e.g.: @now/go@0.0.1)

The cache will be invalidated if any of those items changes. The user can bypass the cache by running now -f.

Limits

  • Builders can run for a maximum of 5 minutes before the execution times out.
  • The maximum cache archive size of a Builder is 100mb.
  • The cache TTL is 7 days.

Including Additional Files

Most Builders use static analysis to determine which source files should be included in the Lambda output based on the build src input. Any unused code or assets is ignored to ensure your Lambda is as small as possible.

In some cases, you may wish to include templates or views that are not able to be statically analyzed. Builders provide a configuration for includeFiles that accepts an array of globs that will always be included in the Lambda output.

{
  "builds": [
    {
      "src": "index.js",
      "use": "@now/node",
      "config": {
        "includeFiles": [
          "templates/**",
          "views/**"
        ]
      }
    }
  ]
}

Using the @now/node Builder and configuring the includeFiles within a now.json configuration file.

Official Builders

Listed below are all official Builders from ZEIT.

Builder
Description
The Static Builder takes any file as an entrypoint and moves it to the deployment as a static file.
The Static Builds Builder takes a package.json or build.sh file as an entrypoint and executes a command within them to produce static files in a dist directory to serve.
The Node.js Builder takes an entrypoint of a Node.js function, builds its dependencies (if any) and bundles them into a Lambda.
The 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.
The Go Builder takes in a Go program that defines a singular HTTP handler and outputs it as a Lambda.
The PHP Builder takes .php files as an entrypoint and makes them available as Lambdas.
The Python Builder takes in a Python program that defines a singular HTTP handler and outputs it as a Lambda.
This Builder takes in a Rust program and outputs it as a Lambda.
The Bash Builder takes an entrypoint of a bash function, imports its dependencies, and bundles them into a Lambda.
The mdx-deck Builder takes an .mdx file as an entrypoint and builds it as an mdx-deck output.
The OptiPNG Builder optimizes .png entrypoints using OptiPNG.
The HTML Minifier Builder optimizes .html entrypoints using html-minifier.
The Markdown Builder converts Markdown to output HTML files.