Builders Overview

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.

Was this helpful?