Skip to main content

Setting Environment Variables

Local Development

In order to fetch data from the WordPress instance, Next.js needs to know the endpoint at build time. For local development, the starter kit uses dotenv.

In your projects .env.development.local file, update the WPGRAPHQL_URL and IMAGE_DOMAIN with your WordPress GraphQL endpoint, and the IMAGE_DOMAIN. If the WPGRAPHQL_URL and IMAGE_DOMAIN are the same, you can omit setting the IMAGE_DOMAIN.

For example:


Connecting to Multidev Environments

To connect to a Multidev environment, the PANTHEON_ENVIRONMENT environment variable can be used inside of next.config.js.

Either the PANTHEON_CMS_ENDPOINT or WPGRAPHQL_URL will need to be set.

The PANTHEON_CMS_ENDPOINT can be mocked for local development by defining it in the .env.development.local.

Taking a look at how the next.config.js works, there is this logic which sets the backendUrl.

let backendUrl, imageDomain;
if (process.env.WPGRAPHQL_URL === undefined) {
backendUrl = `https://${process.env.PANTHEON_CMS_ENDPOINT}/wp/graphql`;
imageDomain = process.env.IMAGE_DOMAIN || process.env.PANTHEON_CMS_ENDPOINT;

// populate WPGRAPHQL_URL as a fallback and for build scripts
process.env.WPGRAPHQL_URL = `https://${process.env.PANTHEON_CMS_ENDPOINT}/wp/graphql`;
} else {
backendUrl = process.env.WPGRAPHQL_URL;
imageDomain =
process.env.IMAGE_DOMAIN ||
process.env.WPGRAPHQL_URL.replace(/\/wp\/graphql$/, '').replace(

In order to connect to a Multidev backend, this backendUrl will need to be updated. PANTHEON_ENVIRONMENT includes a PR number or integration branch name.

This code could be added under the above logic to connect to a Multidev that is prefixed with the branch name of my site.

* PANTHEON_ENVIRONMENT is equal to `multi-demo` since that is the name of my branch. I will use this variable to create a `backendUrl` which points
* to my Multidev backend.
if (process.env.PANTHEON_ENVIRONMENT !== 'live') {
backendUrl = `https://${
}-${backendUrl.replace(/^https?:\/\/[^-]*-/, '')}`;

Decoupled Preview

To enable Decoupled Preview, the following environment variables must be set in the .env.development.local for local dev and in the Pantheon dashboard for production or Multidev environments.

  • PREVIEW_SECRET - The secret used on creation of a new preview site in the WP dashboard
  • WP_APPLICATION_USERNAME - To be set as the username found and set in the Users tab of the WP dashboard
  • WP_APPLICATION_PASSWORD - To be set as the password created for the WP application user. Passwords can be set through selecting a user inside the Users tab of the WP dashboard

Setting The Path Prefix

See the Next.js guide on Adding a Base Path for information on setting the basePrefix if you are not using the starter kit.

  • PANTHEON_UPLOAD_PATH - Used to deploy a your application under a sub-path of a domain. This will be automatically set as the basePath in the next.config.js. To test this locally, set the PANTHEON_UPLOAD_PATH in your .env.development.local to the path you would like to test.