{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"environment-variables","__idx":0},"children":["Environment variables"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define environment variables to customize behavior or content in your developer portal projects."," ","You create environment variables in two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the shell (in your local environment, CI, or in our hosted ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/settings/environment-variables"},"children":["Workflows settings"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/environment-files"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.*"]}," files"]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Precedence"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.*"]}," files take precedence over shell-defined environment variables."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See this environment compatibility table."," ","Workflows sets the shell environment variables in the hosted build environment."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Shell (local or CI)"},"children":["Shell (local or CI)"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Workflows"},"children":["Workflows"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":".env files"},"children":[".env files"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Development"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production (Workflows hosted)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Previews (Workflows hosted)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On-premise"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use built-in environment variables to control portal behavior:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/environment-variables-built-in"},"children":["built-in environment variable"]}," and corresponding value in your shell or in ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/settings/environment-variables"},"children":["Workflows settings"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or, use custom environment variables in portals by following these steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define the variable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allow the variable to be used (required for shell and Workflows variables)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify pre-requisites."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Insert the variable name as a placeholder where you want it to apply during the build."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Build the portal."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-define-the-variable","__idx":1},"children":["Step 1: Define the variable"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.*"]}," files take precedence over shell or Workflows variables."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MY_ENV_VAR"]}," has value ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yes"]}," in the shell execution environment, but a value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.production"]}," file, the value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MY_ENV_VAR"]}," would be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no"]}," (in the production environment)."]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create one or more ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/environment-files"},"children":["environment files"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/settings/environment-variables"},"children":["variables in Workflows settings"]}," (or in your shell for local or on-premise builds)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-allow-the-variable-client-side","__idx":2},"children":["Step 2: Allow the variable client-side"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Shell and Workflows environment variables are not available client-side unless explicitly allowed by listing them in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/siteconfig/env-variables"},"children":["envVariablesAllowedClientSide"]}," section of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.*"]}," file variables are automatically allowed and do not need to be listed in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use cases include using the variable inside:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Markdown files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MDX files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["YAML files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TypeScript/JavaScript files"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Allowed in environment file","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"MY_VARIABLE=Hello\nCUSTOM_PATH=/docs/helpdesk\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Allowed in siteConfig file","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"seo:\n  title: Example Developer Portal\n  description: Learn how to work with Example APIs\nenvVariablesAllowedClientSide:\n  - MY_VARIABLE\n  - CUSTOM_PATH\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Secrets should never be allowed client-side (or stored in files in source control)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-check-prerequisites","__idx":3},"children":["Step 3: Check prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before using the environment variable in your portal files, follow the prerequisites checklist to prevent issues:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Created files for every environment (eg ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.development"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.production"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," No secrets are in the files."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Added any shell environment variables for production builds explicitly to Redocly Workflows on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Portal > Settings > Environment variables"]}," page (or to your on-premise build tool)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Defined allowed shell or Workflows variables within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Avoided reserved environment variables including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HOME"]}," and Node-related variables."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-use-the-variable","__idx":4},"children":["Step 4: Use the variable"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Environment variables can be used in the following file types:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Markdown and MDX"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["YAML, including portal configuration files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["JavaScript and TypeScript, including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.ts"]}," file"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"usage-in-markdown-and-yaml-files","__idx":5},"children":["Usage in Markdown and YAML files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Markdown and YAML files, insert an environment variable with notation like this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{process.env.MY_ENV_VAR}}"]},"."," ","It must have double curly braces and be prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["process.env."]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Markdown example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"md","header":{"controls":{"copy":{}}},"source":"This is a Markdown file.\n\nHere is an example. My name is `{{process.env.MY_ENV_NAME}}`.\n","lang":"md"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"siteConfig example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"meta:\n  title: { { process.env.MY_TITLE } }\n  description: My example developer portal\nlogo: ./images/logo.png\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"usage-in-javascript-typescript-and-mdx-files","__idx":6},"children":["Usage in JavaScript, TypeScript and MDX files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["MDX files are special because they can contain both JSX and Markdown inside a single file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In JSX sections of the file, use curly braces. This is a special syntax that instructs the JSX parser to interpret the contents between braces as JavaScript instead of a string (see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{process.env.WELCOME_MESSAGE}"]}," in the example)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Markdown sections of the file, the syntax requires double curly braces (see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{process.env.WELCOME_MESSAGE}}"]}," in the example)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In both cases, the environment variable name must be prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["process.env."]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"<Jumbotron>\n  <NavBar location={props.location} standalone={false} />\n  <H1>Heading In Here Big Text {process.env.WELCOME_MESSAGE}</H1>\n  <H2>Description in here with some more text</H2>\n  <Flex p={20} justifyContent=\"center\">\n    <Button inversed large to=\"/test.txt\">\n      Get Redocly\n    </Button>\n    <Button inversed transparent large to=\"/markdown\">\n      Get Started\n    </Button>\n  </Flex>\n</Jumbotron>\n\n<!-- plain markdown section -->\n# Regular Markdown content example {{process.env.WELCOME_MESSAGE}}\n\nMore Markdown text.\n<!-- end plain markdown section -->\n\n<Box>\n  More JSX content\n</Box>\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In JavaScript and TypeScript files, the syntax doesn't require braces, but the variable name must be prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["process.env."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows how to insert an environment variable in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.ts"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"export const theme = {\n  // ...\n  colors: {\n    primary: {\n      main: process.env.REDOCLY_MAIN_COLOR,\n      // ...\n    },\n  },\n  // ...\n};\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-build-the-portal","__idx":7},"children":["Step 5: Build the portal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you have defined your environment variables and modified all files where you want to apply them, make sure your changes are pushed to Workflows."," ","The app applies your environment variables during the next build."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For on-premise portals, you must run the build manually."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For local development, restart your development server."]}]},"frontmatter":{"seo":{"title":"How to use environment variables in your developer portal"},"excludeFromSearch":true},"tagList":["admonition","partial","tab","tabs"],"title":"How to use environment variables in your developer portal","lastModified":"2025-05-28T16:01:32.000Z"}