Environments

Environments allow you to modify content models without affecting production content. You can test model changes against your content in isolation before pushing the changes to production.

An environment clones content from your production repository into a new repository, including:

• Content models (page types, slices, and custom types)
• Pages
• Media files

The following are not cloned into new environments:

• Users (user permissions are shared between environments)
• Integration field catalogs (catalogs are shared between environments)
• Webhooks

How to create an environment

• Open your environment settings

  Navigate to your Prismic repository and go to Settings > Environments.

  You must be the repository owner or have admin rights to access the Environments page.

• Create an environment

  In the Environments section, create an environment using the following values:

  Field	Value
  Name	The name that content writers see. It also determines the environment’s URL.
  Choose an environment to clone	The base environment used to copy content and settings.

  Click Create a new environment after filling in the values.

• Sync content

  Prismic will automatically start to clone content from the selected base environment into the new environment.

  You can access the new environment once everything is synced.

Local development

Prismic’s local development tool, Slice Machine, supports environments. The active development environment can be changed in Slice Machine using the drop down in the top-left corner.

You can immediately modify and push content model changes to the selected environment.

Access the selected development environment

Slice Machine automatically sets an environment variable in your project with the selected development environment. The name of the environment variable depends on your website’s framework:

• Next.js: NEXT_PUBLIC_PRISMIC_ENVIRONMENT
• Nuxt: NUXT_PUBLIC_PRISMIC_ENVIRONMENT
• SvelteKit: VITE_PRISMIC_ENVIRONMENT

These variable names follow each framework’s standard conventions for environment variables.

The environment variable is deleted when the production repository is selected.

Fetch content from a development environment

You can configure your Prismic client to fetch content from the selected environment. How you update the client depends on which framework your website uses.

export const repositoryName =
  process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT || sm.repositoryName; 

Push changes to production

Once your content model changes have been tested in your development environment, you can push them to your production repository.

• (Optional) Commit your changes to Git

  If you are using Git or another version control system (VCS), commit your model changes. You’ll be able to undo your changes through your VCS if necessary.

• Change to the production environment

  In Slice Machine, change to the production environment using the drop down in the top-left corner.

  

• Push to Prismic

  Click Review changes in the sidebar. You should see your model changes listed.

  If the changes look correct, click the Push button in the top-right corner.

  

  The Page Builder will now recognize your changes.

Resync content

Over time, an environment’s content will diverge from the production repository. You can resync content and its models from the production repository at any time.

We recommend resyncing at the start of each website development cycle, such as starting to add a new slice or website feature.

• Open your environment settings

  Navigate to your Prismic repository and go to Settings > Environments.

  You must be the repository owner or have admin rights to access the Environments page.

• Resync content

  In the Environments section, locate your environment and click its Resync button.

  

  Prismic will start to sync content from the base environment into your environment.

FAQs

Should I use environments for staging content?

No. Environments are only meant for making changes to content models without endangering the production repository’s content.

We recommend that content writers stay on the production repository to author new content. Content writers can use releases and previews to review content on the front-end before publishing.

Why is content missing after pushing changes?

In most cases, this happens because a page type, custom type, or field’s API ID was renamed. Changing an API ID is effectively the same as removing the model (along with the model’s content) and adding a new one with the updated API ID.

If you need to rename a model, we recommend not editing its API ID and renaming its label instead. Existing content will be retained and content writers will see the new label.

We recommend testing content model changes in a development environment to protect your production content.

Can I use “development” endpoints for an integration field?

Yes. Read the following guide to understand how the integration field and environments can work together and how you can configure a different integration endpoint on your cloned environments.