Environment Variables

With chayns-toolkit@3 .env-files are automatically loaded depending on the current environment which is defined as process.env.BUILD_ENV || (!development ? 'production' : 'development'). This will load up to 4 files, with the files listed at the bottom having higher priority:

.env.env.local.env.{environment}.env.{environment}.local

Unlike previous versions only variables starting with PUBLIC_ are exposed to your app, while others are only available in your toolkit.config.js to modify the config.

These values can be accessed in your code on the process.env or import.meta.env namespace:

const API_KEY = process.env.GOOGLE_MAPS_API_KEY// orconst API_KEY = import.meta.env.GOOGLE_MAPS_API_KEY

Default Variables#

The chayns-toolkit will define following variables by default:

process.env.VERSION
import.meta.env.VERSION
process.env.BUILD_VERSION
import.env.BUILD_VERSION
process.env.BUILD_ENV
import.meta.env.BUILD_ENV
process.env.__PACKAGE_NAME__
import.meta.env.__PACKAGE_NAME__
__REQUIRED_REACT_VERSION__

Rsbuild also injects some variables by default, for further information check their documentation.

How to Use It Correctly#

Keep your .env*.local-files in your .gitignore file and do not push them to source control.

Set environment variables in your CI/CD solution (e.g. Vercel, TeamCity) directly. Here's a guide on how to do that for TeamCity.

If you want your app to behave differently for each build environment, e.g. use a QA backend when doing QA tests, set process.env.BUILD_ENV to qa and define a variable in the .env.qa-file.

Caveats#

During compilation, chayns-toolkit will look at your source code and look for places where you access process.env. It will then match these places with the available environment variables and do a string replacement if it can find one.

In other words this means that you cannot access the variables with any other syntax. Only process.env.VAR_NAME will be replaced, but other syntax like const { VAR_NAME } = process.env will not be detected.

⚠️ Unlike in older versions not defined variables will not be replaced anymore and could cause runtime errors.

⚠️ The content below is only relevant for versions older than 3.

All system environment variables as well as any variables specified in a .env.local file in the root of your project directory will be available to your code under process.env.VAR_NAME.

Starting with version 2.0.12 .env-files are also loaded according to the current environment. This way up to 4 files can be loaded, with the files listed at the bottom having higher priority.

.env.env.local.env.{environment}.env.{environment}.local

Example#

Your .env.local file would look something like this:

/.env.local

GOOGLE_MAPS_API_KEY=1bc29b36f623ba82aaf6724fd3b16718OTHER_IMPORTANT_API_KEY=ca794fb2d950acf25c964ecc35f2d7e2... other values ...

These values can be accessed in your code on the process.env namespace:

const API_KEY = process.env.GOOGLE_MAPS_API_KEY

How to Use It Correctly#

Keep your .env.local in your .gitignore file and not push it to source control.

Set environment variables in your CI/CD solution (e.g. Vercel, TeamCity) directly. Here's a guide on how to do that for TeamCity.

If you want your app to behave differently for each build environment, e.g. use a QA backend when doing QA tests, use an environment variable for it (BUILD_ENV for example). Set a different value for this environment variable for every build environment (BUILD_ENV=qa, BUILD_ENV=production, etc.).