Environment variables

Provide environment variables to customize behavior or content in your developer portal.

Defining your variables

Define your variables in either a .env.* file or in the shell of the environment used at build-time.

Environment files

Use an environment file with the following conventions:

• must be in the root of your project repository
• must start with .env.
• must end with the environment's name (eg. production or development)

Sample names:

• .env.production
• .env.development

By default, Redocly will use .env.development for your local development server, and .env.production in our production build.

Override which environment file is used by setting an environment variable named REDOCLY_ACTIVE_ENV.

Given this environment variable setting (REDOCLY_ACTIVE_ENV=production-example), Redocly would look for the .env.production-example in your project root.

Here is an example .env.* file. Remember, do not store secrets in these files.

MY_ENV_VAR=yes
PRIMARY_COLOR=orange
WELCOME_MESSAGE=Welcome

Environment variables

Environment variables are set in your shell for the development environment.

MY_ENV_VAR=yes yarn start

In production and previews, environment variables must be set within the Redocly Workflows user interface from the corresponding developer portal's Settings > Environment variables page.

Secrets should never be allowed client side.

Allowed client-side

Redocly prevents variables from being embedded into the client-side code with these exceptions:

• Variables explicitly defined in a .env.* file.
• Variables defined in the siteConfig.yaml property envVariablesAllowedClientSide.
• Variables starting with REDOCLY_.

Here is an example from the siteConfig.yaml file:

envVariablesAllowedClientSide:
  - ANOTHER_VARIABLE
  - MY_ENV_VAR

Reserved variables

Some variables are reserved including HOME and others related to the node environment.

Precedence

Environment variables take precedence over environment files.

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 yes (in the production environment).

Environment variables definition checklist

• Created files for every environment (eg .env.development and .env.production).
• No secrets are in the files.
• Add any environment variables for production builds explicitly to Redocly Workflows on the Developer portal > Settings > Environment variables page.
• Defined allowed variables within the siteConfig.yaml.
• Avoided reserved environment variables including HOME and node env-related variables.

Using environment variables

Allowed environment variables are embedded into the client-side code as shown in the section above.

Usage in markdown and YAML files

In markdown or YAML files, use an environment variable with notation like this {{process.env.MY_ENV_VAR}}. It must have double-curly braces and be prefixed with the process.env..

Here is an example. My name is `{{process.env.MY_ENV_NAME}}`.

meta:
  title: {{process.env.MY_TITLE}}

Usage in JavaScript, TypeScript and MDX files

MDX files are special, because they can have both JSX and markdown inside a single file.

In JSX the curly braces are a special syntax to let the JSX parser know that it needs to interpret the contents in between them as JavaScript instead of a string (see {process.env.WELCOME_MESSAGE} in the example). In the markdown section, the syntax involves double curly braces (see {{process.env.WELCOME_MESSAGE}} in the example).

<Jumbotron>
  <NavBar location={props.location} standalone={false} />
  <H1>Heading In Here Big Text {process.env.WELCOME_MESSAGE}</H1>
  <H2>Description in here with some more text</H2>
  <Flex p={20} justifyContent="center">
    <Button inversed large to="/test.txt">
      Get Redocly
    </Button>
    <Button inversed transparent large to="/markdown">
      Get Started
    </Button>
  </Flex>
</Jumbotron>

<!-- plain markdown section -->
# Here some regular md content coming {{process.env.WELCOME_MESSAGE}}
Lorem ipsum
<!-- end plain markdown section -->

<Box>
  Some more jsx
</Box>

Use environment variable in JavaScript and TypeScript files, such as the theme.ts file like this:

export const theme = {
  // ...
  colors: {
    primary: {
      main: process.env.REDOCLY_MAIN_COLOR
    // ...
    }
  }
  // ...
}