Our build environment is quite flexible about what you can do — but there are some things we do automatically. For a full breakdown of “how it works”, see this blog post:
When it comes to setting up your build pipeline on Netlify, the hope is that it will take minimal to no effort to build the site the same way you already do. The most common configuration is intended not to be “change your build pipeline” but instead “choose the appropriate version of the tools we’ll use automatically for you, so they work the same as they do in your local environment”. This document describes the variables that can affect what version of Ruby, Node, NPM, YARN, Python, and Hugo we use. All of the installing of dependencies described here happens before your build command is run — so you can include
webpack in your
/package.json and be confident that it will be
npm install‘ed before we run your build command
In addition to the below variables you can set, we automatically set some variables you can key off of in your builds. These are listed in this documentation . To configure additional build variables, you can do it either per-site in your site settings (Settings > Build & Deploy > Continuous Deployment > Build Environment Variables) or via
netlify.toml is parsed per-build and allows you to set per-build, per-branch, or per-deploy-type settings — as well as global settings.
Build Environment Variables
Node, NPM, and Yarn
NODE_ENVis by default set to
development(typical settings: production or development; setting globally allows all dependency installations to work with our caching.)
NODE_VERSIONis by default pinned to version that we had systemwide when you created your site. Best practice is to set explicitly via a
/.nvmrcfile or a
NODE_VERSIONenvironment variable. Versions possible: any released version.
- If you have a
/yarn.lockfile: you can set
YARN_VERSION(any released version),
YARN_FLAGS(flags to pass to our automatic
yarn installthat runs when this file is present).
YARN_FLAGSis set to
/package.jsonfile is ignored in regards to the next step below if you have a
- If instead you have a
/package.jsonfile: you can set
NPM_VERSION(any released version),
NPM_FLAGS(flags to pass to our automatic
npm installthat runs when this file is present AND there is no
NPM_VERSIONis not needed — we’ll use the version that shipped with the version of Node.js being used.
- If you use NPM, then you can set an
NPM_TOKENenvironment variable which we can be configured to use to fetch dependencies from npmjs.org. For more details about how to configure things, this gist describes the workflow.
/Gemfile.lockare required to list dependencies (e.g. “jekyll” or “middleman”) which your build needs. You can use
bundle installto create
Gemfile.lockfrom a Gemfile, whose contents must follow this specification.
- Set Ruby version via a
/.ruby-versionfile. You must choose from among rvm’s supported versions. Note that the syntax for this file is JUST the version number:
x.y.z, with no trailing newline. As of this writing, the following versions are already installed and will create the fastest builds.
pip installautomagically run against it. It must follow this specification.
/runtime.txtmay list a python version to use from the list of pre-installed pythons (see this file in our build-image repository for the up-to-date list). Note that the syntax for this file is JUST the version number:
x.y, with no trailing newline. As of this writing, the supported versions include:
- By default we’ll use the Hugo version that we had set as default when you created your site. As of this writing, that is “version 0.17” for almost everyone.
- You can change this in two ways:
HUGO_VERSIONenvironment variable can be set to the version string for any released version after 0.19, and if you set this, you can set your build command to simply
hugo. Please read this blog post for more details about how we handle this.
- If you want to use an older versions you can instead run different build commands:
- If there is a
/bower.jsonfile we’ll automatically run
bower install --config.interactive=falseagainst it to install your bower dependencies. This is IN ADDITION TO running
yarn installas described above
- We automatically provide grunt for you in the build environment in case your build command references it. We’ll run
npm install grunt-clifor you before running your build command, in case your build command contains the string
Additional variables that can affect the build:
- If you set a
GIT_LFS_ENABLEDvariable, we’ll use
git lfs cloneto check out your repository — otherwise we just use
Notice something is incorrect or outdated?
First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.