This guide shows you how to create production, staging, and other environments.

In order to serve your site on a specific domain, you need to configure an environment. Most sites have at least three environments: default, staging, and production. Free accounts are limited to three environments. Paid accounts allow you to create either five environments (on the Hyper plan) or as many environments as you need (on Enterprise plans). Each environment consists of:

  • Domains - one or more domains on which the site will be served. Domains cannot be set on the default environment. The domain name for the default environment is derived from your team and site's name.
  • Environment Variables - secrets and other values that are specific to the environment and are not appropriate to check into source control. For example, API keys are commonly stored as environment variables.
  • Split Testing - Split traffic between multiple router destinations or other environments to conduct A/B testing or implement blue/green deployments.
  • Caching - Each environment has a separate cache space that is automatically cleared each time you deploy. Use the Caching tab to clear the cache by path or surrogate key.

To create an environment, navigate to your site and select the Environments tab, and click New Environment:


When creating an environment, you can choose whether or not to limit deployment capabilities to admins and deploy tokens, or to make it available to all members of the team:

limit environment

To deploy to an environment, you can layer0 deploy with the --environment option:

layer0 deploy <team name> --environment=<environment name>

You can also promote any existing deployment to an environment using the Promote to Environment button at the top of the deployment view:


When configuring CI, we recommend:

  • Automatically deploying to your staging environment when a PR is merged to the master branch of your repo.
  • Manually promoting deployments to production using the Layer0 Console to prevent unwanted builds from being published by misconfigured CI workflows.

To ensure that your production environment gets priority over all other environments during periods of high traffic, mark it as "production" by selecting this option during creation:


Or from the environments list in the site view:


Failure to do so could cause your production environment to become slow if another environment experiences an unexpected surge in traffic, for example due to an attack or load test.

Since environments contain important settings that affect how your site functions, they are versioned. This makes it easy to roll back to a previous version of the environment if you make a change that breaks the site. To change your environment settings, create a new draft version by clicking the Edit button:


As you make changes they are saved in the draft version. Once you're ready to deploy your changes, click Activate.


Doing so will redeploy the environment's active deployment, but updated with the new environment configuration.

The variables you configure on an environment can be accessed in your code using process.env. A common use case is to configure different backend host names in layer0.config.js based on the environment. Here is an example where the origin backend is determined by a HOST environment variable.

// layer0.config.js
const defaultHostname = ''

module.exports = {
  backends: {
    origin: {
      domainOrIp: process.env.HOST || defaultHostname, // Falling back to defaultHostname is needed during the initial
      hostHeader: process.env.HOST || defaultHostname, // deployment of your site, when an environment is not yet configured.

Note that your layer0.config.js file is loaded during deployment to configure the edge for your environment. The first time you deploy your site, there won't be any environment variables defined, so you need to include defaults in layer0.config.js as shown in the example above.

Layer0 automatically injects the following environment variables:

  • NODE_ENV: Set to production by default, but you can override this through the console.
  • LAYER0_ENVIRONMENT_NAME: The name of the environment (e.g. default, production and so on). This cannot be overriden by you.

As of Layer0 CLI version 2.19.0, when you deploy to an environment using a deploy token, for example by running layer0 deploy my-team --environment=production --token=(my token) option, all environment variables are pulled down from the Layer0 Developer Console and applied to process.env so they can be accessed at build time. This allows you to store all of your build and runtime secrets in a single place, the Layer0 Developer Console, rather than storing some in your CI system's secret manager.

To configure secrets during local development, we recommend using dotenv. If you would like to reference environment variables read from .env in layer0.config.js, add the following at the top of layer0.config.js:

// layer0.config.js
Edit this guide on GitHub