Cloudflare Docs
Visit Pages on GitHub
Set theme to dark (⇧+D)

Build configuration

You may tell Cloudflare Pages how your site needs to be built as well as where its output files will be located.

​​ Build commands and directories

You should provide a build command to tell Cloudflare Pages how to build your application. For projects not listed here, consider reading the tool’s documentation or framework, and submit a pull request to add it here.

Build directories indicates where your project’s build command outputs the built version of your Cloudflare Pages site. Often, this defaults to the industry-standard public, but you may find that you need to customize it.

Understanding your build configuration

The build command is provided by your framework. For example, the Gatsby framework uses gatsby build as its build command. When you are working without a framework, leave the Build command field blank.

The build directory is generated from the build command. Each framework has its own naming convention, for example, the build output directory is named /public for many frameworks.

The root directory is where your site’s content lives. If not specified, Cloudflare assumes that your linked git repository is the root directory. The root directory needs to be specified in cases like monorepos, where there may be multiple projects in one repository.

​​ Framework presets

Cloudflare maintains a list of build configurations for popular frameworks and tools. These are accessible during project creation. Below are some standard build commands and directories for popular frameworks and tools.

If you are not using a framework, leave the Build command field blank.

Framework/toolBuild commandBuild directory
Angular (Angular CLI)ng builddist
Astronpm run builddist
Brunchbrunch build --productionpublic
Docusaurusnpm run buildbuild
Ember.jsember builddist
Expoexpo build:webweb-build
Gatsbygatsby buildpublic
GitBookgitbook build_book
Gridsomegridsome builddist
Jekylljekyll build_site
Jigsawvendor/bin/jigsaw build productionbuild_production
Mkdocsmkdocs buildsite
Next.js (Static HTML Export)next build && next exportout
Nuxt.jsnuxt generatedist
Pelicanpelican content [-s]output
Quasarquasar builddist/spa
React (create-react-app)npm run buildbuild
React Staticreact-static builddist
Remixnpm run buildpublic
Sveltenpm run buildpublic
Umiumi builddist
Vuenpm run buildpublic
VuePressvuepress build $directory$directory/.vuepress/dist

​​ Environment variables

If your project makes use of environment variables to build your site, you can provide custom environment variables by going to Account Home > Pages > your Pages project > Settings > Environment variables.

The following system environment variables are injected by default (but can be overridden):

Environment VariableInjected valueExample use-case
CF_PAGES1Changing build behaviour when run on Pages versus locally
CF_PAGES_COMMIT_SHA<sha1-hash-of-current-commit>Passing current commit ID to error reporting, for example, Sentry
CF_PAGES_BRANCH<branch-name-of-current-deployment>Customizing build based on branch, for example, disabling debug logging on production
CF_PAGES_URL<url-of-current-deployment>Allowing build tools to know the URL the page will be deployed at

​​ Language support and tools

Cloudflare Pages' build environment has broad support for a variety of languages, such as Ruby, Node.js, Python, PHP, and Go.

If you need to use a specific version of a language, (for example, Node.js or Ruby) you can specify it by providing an associated environment variable in your build configuration, or setting the relevant file in your source code.

Here are the pinned versions for tools included in the Cloudflare Workers build environment, and how to override them as relevant:

LanguageDefault versionSupported versionsEnvironment variableFile
Elixir1.71.7 only
Emacs2525 only
Erlang2121 only
Go1.14.4Any versionGO_VERSION
Java88 only
Node.js12.18.0Any version up to 17.xNODE_VERSION.nvmrc, .node-version
PHP5.65.6, 7.2, 7.4 onlyPHP_VERSION
Python2.72.7, 3.5, 3.7 onlyPYTHON_VERSIONruntime.txt, Pipfile
Ruby2.6.2Any version between 2.6.2 and 2.7.5RUBY_VERSION.ruby-version
Swift5.2Any 5.x versionSWIFT_VERSION.swift-version

Many common tools have been pre-installed as well. The environment variable available for overriding the pinned version is specified, as available:

ToolsDefault versionSupported versionsEnvironment variable
DoxygenVersion 1.8.6
EmacsVersion 25
Gutenberg(requires environment variable)Any versionGUTENBERG_VERSION
HugoVersion 0.54.0Any versionHUGO_VERSION
GNU MakeVersion 3.8.1
ImageMagickVersion 6.7.7
jqVersion 1.5
OptiPNGVersion 0.6.4
NPMCorresponds with Node.js versionAny versionNPM_VERSION
pipVersion corresponding with Python version
PipenvLatest version
sqlite3Version 3.11.0
YarnVersion 1.22.10Any version from 0.2.0 to 1.22.19YARN_VERSION
Zola(requires environment variable)Any version from 0.5.0 to 0.14.0ZOLA_VERSION

If you want to set a specific version of a framework your Cloudflare Pages project is using, note that Pages will respect your package manager of choice during your build process. For example, if you use Gatsby.js, your package.json should indicate a version of the gatsby npm package, which will be installed using npm install as your project builds on Cloudflare Pages.