Environments

In this article, you'll learn what environments are and how to use them to safely iterate your custom types.


Environments involve creating clones of your repository. This feature is included with all Enterprise plans and is available as a paid option on yearly Platinum plans paid via invoice. To enable this feature, please book a call with our team.

Prismic environments allow you to clone the entirety of your production repository, copying all custom types, documents, and media files.

This is useful if, for example, you have a continuous development cycle and regularly implement new website designs, or if you want to iterate your custom types in isolation.

The user base stays independent, ensuring that only the relevant developers and content editors access the development environment.

How to add a new environment

If your repository is on a Platinum plan or an Enterprise plan and you're an Administrator, you can clone your repository directly from the UI. If you don't see that option in your repository settings, please reach out to your account manager.

Switch environments in Slice Machine

Slice Machine will automatically detect your Prismic environments and allows you to switch between them with a toggle.

To enable environments in Slice Machine, ensure you have the latest version of slice-machine-ui and your adapter installed, then follow the instructions for your framework, below.

Your repositoryName should be your main repository

Previously, we recommended changing the repositoryName in slicemachine.config.json in order to change environments. This is no longer the case. Slice Machine will automatically detect the environments in your repository and provide a selector. The repositoryName property in your slicemachine.config.json should always point to your main repository.

Next.js

Update packages:

Copy
npm i -D slice-machine-ui@latest @slicemachine/adapter-next@latest

Update prismicio.js:

prismicio.js
Copy

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

Update your .gitignore file:

.gitignore
Copy
 .env.local

Nuxt

Update packages:

  • Nuxt 3
  • Nuxt 2
Nuxt 3
Copy
npm i -D slice-machine-ui@latest @nuxtjs/prismic@latest @slicemachine/adapter-nuxt@latest
Nuxt 2
Copy
npm i -D slice-machine-ui@latest @nuxtjs/prismic@latest @slicemachine/adapter-nuxt2@latest

In Nuxt, you don’t need to update your API config. @nuxtjs/prismic will handle the config automatically.

Update your .gitignore file:

.gitignore
Copy
+ .env

SvelteKit

Update packages:

Copy
npm i -D slice-machine-ui@latest @slicemachine/adapter-next@latest

Update prismicio.js:

prismicio.js
Copy

 export const repositoryName = 
   import.meta.env.VITE_PRISMIC_ENVIRONMENT || config.repositoryName;

Update your .gitignore file:

.gitignore
Copy
 .env.local

Move custom types between environments without Slice Machine

Let's say you need to move an edited custom type from a development environment to a production environment. Here are the steps:

  1. Copy the JSON of the custom types in your development environment, and paste it into the JSON editor of the custom type in the production environment.
  2. Create new documents using the updated custom types in the production repository. These updates can be grouped in a release.
  3. Make the necessary changes in the front end of your project to reflect the changes.

Suppose you're looking into promoting more schema changes from the Development environment to the Production environment. In that case, you can use the Custom Types API to retrieve custom types changes from Development and update the Production environment.

Impact of updating types in production

Adding a new field in a custom type will appear in the API response with default values the first time something is published in the repository.

Adding new fields

We have a simple custom type composed of a title field with the API ID of title and a rich text field with the API ID of content. Before making any changes, here is the data we receive from the API for that document:

Copy
"data": {
  "title": "My article title",
  "content": "My article content"
}

Then, if you add a new field — for example, a key text field with the API ID of author to the custom type — the API response will remain the same until the next document is published in the repository. If no content has been populated for that new field, the API will return this field with a default value:

Copy
"data": {
  "title": "My article title",
  "content": "My article content",
  "author": null
}

Note about removing or renaming the API ID of a field. You cannot rename the API ID of a field. Renaming a field is equivalent to deleting an old field and creating a new one, meaning that the content won't be migrated. Read more here: Change the API ID of a field.

Should I use environments for staging content?

No, these environments are only meant for updating the codebase or the custom types without endangering the production repository.

We recommend that content editors stay on the production repository to author new content and use releases and Previews to check the presentation on the front-end before publishing it.

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.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.