Environment variables#

This page describes environment variables and their usage for configuration of your Volto application at runtime.

Runtime environment variables#

New in version 13.

All configurable environment variables work at runtime, not only at build time. You could, for example, build your Volto application, then start it in production with the RAZZLE_API_PATH environment variable.

yarn build && RAZZLE_API_PATH=https://plone.org yarn start:prod

This brings you a lot of power since you don't have to rebuild on every configuration change. You can also generate builds on your continuous integration, then deploy them anywhere.

Environment variable reference#

ADDONS#

You can use the ADDONS environment variable to enable and configure add-ons in your project.

When running your app, the add-ons will be loaded in the following order:

  • the file package.json

  • programmatically set in the file volto.config.js

  • the environment variable ADDONS

In the environment variable ADDONS, you can specify:

  • released (or published) packages that were installed previously in your environment and are already present in the node_modules directory,

  • or add-ons located in the packages folder of your project, such as Volto's testing packages.

ADDONS can be used to temporarily add an add-on to your build for testing purposes.

yarn add volto-slate
ADDONS=volto-slate:asDefault yarn start

ADDONS can also be used to temporarily enable a feature or a set of customizations.

# given a folder './packages/coresandbox', like in vanilla Volto
ADDONS=coresandbox:multilingualFixture yarn start

If you need to specify several add-ons, separate them with a semicolon (;):

ADDONS="test-addon;test-addon2" yarn start

You can specify profiles for installation:

ADDONS="test-addon:profile1;test-addon2:profile2" yarn start

The following code snippets demonstrate how to configure add-ons.

First in package.json:

"addons": [
    "@kitconcept/volto-blocks-grid"
]

Then in volto.config.js:

module.exports = {
    addons: ['@eeacms/volto-accordion-block']
}

And finally using ADDONS:

yarn add volto-slate
ADDONS=volto-slate:asDefault yarn start

As a result, your app will load the add-ons in the following order:

  • @kitconcept/volto-blocks-grid

  • @eeacms/volto-accordion-block

  • volto-slate

Important

The ADDONS key is a Volto specific configuration. Simply setting ADDONS doesn't download the JavaScript package. This has to be covered another way, by either installing the add-on package (with yarn add), or loading it as a development package with mrs-developer.

BUILD_DIR#

This is a runtime-only environment variable that directs the build to run Volto from a specific location, other than the default folder build.

yarn
BUILD_DIR=dist node dist/server.js
DEBUG#

It enables several logging points scattered throughout the Volto code. It uses the volto: namespace. You can use it in any number of named scopes, all of which are additive and do not cancel one another, or everywhere.

shadowing enables component shadowing errors. It displays the errors of the non-compliant customizations in the server console. It helps you identify problems with a customization that does not work as you expect.

DEBUG=volto:shadowing yarn start

i18n enables the log of missing internationalization messages in the console.

DEBUG=volto:i18n yarn start

* enables logging everywhere it exists in Volto.

DEBUG=volto:* yarn start
DEBUG_ADDONS_LOADER#

Set DEBUG_ADDONS_LOADER=true to have Volto generate a file, addon-dependency-graph.dot, which contains a graph of all the loaded add-ons. You can use Graphviz to convert this file to an image with:

dot addon-dependency-graph.dot -Tsvg -o out.svg
RAZZLE_LEGACY_TRAVERSE#

If true, Volto will construct API URLs without the /++api++ prefix.

This is not needed if you are using Seamless mode, which is the recommended way to set up your deployments since Volto 14.

However, if you are not able to upgrade the packages plone.restapi (8.12.1 or greater) and plone.rest (2.0.0a1 or greater) in the backend, you can adjust your web server configuration and use the RAZZLE_LEGACY_TRAVERSE flag.

RAZZLE_LEGACY_TRAVERSE=true yarn start:prod
VOLTO_ROBOTSTXT#

You can override the robots.txt file with an environment variable called VOLTO_ROBOTSTXT. This is useful when using the same build on multiple websites (for example a test website) to forbid robots from crawling it. The following example is a two-line shell command.

VOLTO_ROBOTSTXT="User-agent: *
Disallow: /" yarn start

Note

If you want to use the VOLTO_ROBOTSTXT environment variable, your must delete the file public/robots.txt from your project to avoid a conflict.

VOLTOCONFIG#

This environment variable allows you to specify a custom location for volto.config.js.

It can be relative to the current project or absolute.

VOLTOCONFIG=../../volto.config.js yarn start

Access environment variables in a browser#

All environment variables defined at runtime with the "RAZZLE_" prefix are available in your browser under the window.env global object. For example, start the application with an environment variable as shown.

RAZZLE_MY_VARIABLE=some_value build/server.js

In the frontend, you can access this variable in your code with the following.

window.env.RAZZLE_MY_VARIABLE