Last updated

Environment variables

Deprecated docs

The developer portal beta is approaching end of life.

Use Realm and Reunite instead. Read the migration guide.

Define environment variables to customize behavior or content in your developer portal projects. You create environment variables in two ways:

Precedence

The .env.* files take precedence over shell-defined environment variables.

See this environment compatibility table. Workflows sets the shell environment variables in the hosted build environment.

EnvironmentShell (local or CI)Workflows.env files
Development✅❌✅
Production (Workflows hosted)❌✅✅
Previews (Workflows hosted)❌✅✅
On-premise✅❌✅

You can use built-in environment variables to control portal behavior:

  1. Define the built-in environment variable and corresponding value in your shell or in Workflows settings.

Or, use custom environment variables in portals by following these steps:

  1. Define the variable.
  2. Allow the variable to be used (required for shell and Workflows variables).
  3. Verify pre-requisites.
  4. Insert the variable name as a placeholder where you want it to apply during the build.
  5. Build the portal.

Step 1: Define the variable

Important

The .env.* files take precedence over shell or Workflows variables.

For example, if MY_ENV_VAR has value yes in the shell execution environment, but a value of no in the .env.production file, the value of MY_ENV_VAR would be no (in the production environment).

  1. Create one or more environment files.
  2. Set variables in Workflows settings (or in your shell for local or on-premise builds).

Step 2: Allow the variable client-side

Shell and Workflows environment variables are not available client-side unless explicitly allowed by listing them in the envVariablesAllowedClientSide section of the siteConfig.yaml file. The .env.* file variables are automatically allowed and do not need to be listed in the siteConfig.yaml file.

Use cases include using the variable inside:

  • Markdown files
  • MDX files
  • YAML files
  • TypeScript/JavaScript files
MY_VARIABLE=Hello
CUSTOM_PATH=/docs/helpdesk
Important

Secrets should never be allowed client-side (or stored in files in source control).

Step 3: Check prerequisites

Before using the environment variable in your portal files, follow the prerequisites checklist to prevent issues:

  • Created files for every environment (eg .env.development and .env.production).
  • No secrets are in the files.
  • Added any shell environment variables for production builds explicitly to Redocly Workflows on the Portal > Settings > Environment variables page (or to your on-premise build tool).
  • Defined allowed shell or Workflows variables within the siteConfig.yaml.
  • Avoided reserved environment variables including HOME and Node-related variables.

Step 4: Use the variable

Environment variables can be used in the following file types:

  • Markdown and MDX
  • YAML, including portal configuration files
  • JavaScript and TypeScript, including the theme.ts file

Usage in Markdown and YAML files

In Markdown and YAML files, insert an environment variable with notation like this {{process.env.MY_ENV_VAR}}. It must have double curly braces and be prefixed with process.