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, or Go app, 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.

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.
• Default lambda bundled output size is 5mb, however, configurable.

Configuring Lambda Bundle Size

Each lambda output, by default, has a bundle size limit of 5mb to help keep cold boot times low, but can be configured up to 50mb with the maxLambdaSize config option.

The lambda threshold can also be defined by the builder that outputs the lambda (for example, @now/go, by default, is 15mb), but the user configuration takes precedence.

{
  "builds": [
    { "src": "*.go", "use": "@now/go", "config": { "maxLambdaSize": "20mb" } }
  ]
}

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/**"
        ]
      }
    }
  ]
}