Repository Naming Best Practices

Prismic Administrative Support FAQs
1

Naming Convention and Best Practices for Prismic Repositories

When creating Prismic instances for website projects, make sure you adopt the right naming convention strategy to avoid complications later. Follow these recommendations:

Repository Naming Convention

For any project, use the following format for naming the Prismic repository:

Example:

If the project is for "MyBrand," name the repository:

mybrand.prismic.io

This repository will act as the production environment. It’s where you’ll configure the initial setup, create content, and eventually invite end users when the project goes live.

:warning: Repositories cannot be renamed. If you choose an incorrect name for your repository (e.g., mybrand-testing), you’ll have to keep it, which can cause confusion for content creators down the path. Plan your naming carefully.

Key Guidelines

  1. Start with the Production Repository:
    • Begin configuration and content creation directly in the repository that will serve as the production instance.
    • When using the repository creation form, you’re setting up a production repository. Avoid naming it something like mybrand-dev. Instead, name it mybrand, as you’ll have the option to clone this repository to create environments like mybrand-dev later.
    • Configure everything in the production repository and create clones for lower environments (e.g., staging, development) as needed.
  2. Cloning for Lower Environments:
    • You can clone the production repository into lower environments at any time.
    • This approach ensures that configuration and content models are consistent across environments.
  3. Changes to Models (Types, Slices):
    • If you’ve worked on Custom Types or Slices in a lower environment, you can promote them to production using either:
      • Slice Machine, or
      • The Types API for programmatic updates.
  4. Content Management:
    • Populate content directly in the production repository using Releases.
      • Releases allow you to group and preview content and schedule publication.
    • Avoid populating future-release content in lower environments, as migrating it to production later will require scripts, adding unnecessary complexity.
  5. Testing in Lower Environments:
    • Use lower environments to test changes to models or to experiment with features.
    • Once tested, promote the changes to production and avoid redoing the same work manually in multiple environments.

Best Practices Recap

  • Use a meaningful name for production repositories, such as mybrand.prismic.io.
  • Start configuration and content creation directly in the production repository.
  • Clone environments for testing and development instead of trying to promote a dev repository to production.
  • Use Releases for future content in production to simplify previewing and scheduling.
  • Use Slice Machine or the Types API to promote tested model changes to production.
  • Choose your repository name carefully—it cannot be changed later.