Environment Variables (< PagesJS 1.0.0) | Yext Hitchhikers Platform

Yext allows you to define environment variables that are accessible during your build. To declare a variable for a deployed site navigate to Site Settings > Branch Configuration > Branch Settings > Add a Branch Variable.

Two important rules about environment variable usage:

  1. All Pages environment variables are scoped to a specific branch. When configuring your code in platform, it is necessary to ensure that environment variables shared between branches are present in all relevant branches.
  2. In order for the Yext build system to correctly identify environment variables, they all must be prefixed with YEXT_PUBLIC.
light bulb
Environment variables will be exposed to the end user, so never place any secrets in your YEXT_PUBLIC environment variables.

Below we walk through how to reference environment variables in a template and in site-stream.json.

When updating environment variables in the platform, you must trigger a new deploy in order to see those updated values reflected in your website.

new deploy button

Referencing Environment Variables in a Template

In your code, you can access environment variables anywhere in your templates via YEXT_PUBLIC_<Variable Name> . Here is an example:

export const transformProps: TransformProps<ExternalImageData> = async (data) => {
  // Here is a properly named environment variable

  const externalImage = (await fetch(url).then((res: any) =>
  )) as ExternalImage;
  return { ...data, externalImage };

Referencing Environment Variables in site-stream.json

The only exception to the above rule is in the site-stream.json file; environment variable references must be referenced as a string in double quotes. Refer to the example below:

  "$id": "site-entity",
  "filter": {
    "entityIds": ["YEXT_PUBLIC_SITE_ENTITY_ID"]
  "source": "knowledgeGraph",
  "fields": [
  "localization": {
    "locales": ["en"],
    "primary": false

Local Dev

You must have Yext CLI version 0.1_333 or higher to access environment variables in site-stream.json during local development.

For local development, you can place environment variables into a .env file. The local dev toolchain will automatically grab any variables in this file and use them in the local serving flow.

Remember to use the same naming convention by prefixing with YEXT_PUBLIC.

light bulb
If you change your environment variables, you will need to restart your local dev server.

As a best practice, we recommend not checking in your .env file to source control in case secret keys are inadvertently stored there. If you deploy a site with a .env file and branch environment variables configured in platform, the branch environment variables will override values specified in the .env file.