Themes

In this article, you'll learn how to create and use themes to launch projects with Prismic.

A theme is a way to launch everything you need to start up a project. It's made up of two parts:

1. Project code files, with a configuration file and a list of JSON Custom Types
2. A command that launches the project and creates a new repository with Custom Types

In Prismic, we use themes all the time to help users get projects up and running quickly. They are particularly useful for new users since they launch a complete project configured with Prismic with a single terminal command.

To use a theme, create or find a theme as a git repository or ZIP file. Use npx to run prismic-cli theme with the repository's URL:

When you run this command in your terminal, the CLI will ask you to log in or sign up to Prismic if you haven't yet, and then it will ask you to add the name of your new repository.

The command will download the project code locally, create a new Prismic repository with Custom Types, and update the API endpoint in your configuration file. When it's complete, you'll have a project ready to launch.

Let’s walk through the steps to create a theme:

This can be as complex as you want it to be. If you plan on creating something simple like a starter, we recommend you add at least the following elements:

• A 404 page
• Preview configuration
• Templates or components with styling
• A README file with instructions to help the user launch the theme and the project
• Default values to prevent the website from crashing if the user leaves a field empty

Create a file at the root of the project to add the configuration for the theme. This file can be written in any language.

By default, the CLI will look for the string your-repo-name to update the URL to the newly created repository.

You can also create prismic-theme.json with a property replaceRepositoryName set to the name of the project's default repository:

Once you run the theme command, your-repository-name will be replaced with the name of your repository.

Create a folder at the root of your project named custom_types. Inside this folder, create a .json file for each Custom Type. You can create this JSON object by building a Custom Type with the drag-and-drop Custom Type Builder in a Prismic repository, and then copying the resulting JSON from the JSON editor of the Custom Type builder.

You can add up to 20 Custom Types. Paste the JSON of each Custom Type in their respective files.

Next, inside the same custom_types folder, create an index.json file. This will contain the metadata for each of the Custom Types. Use the following format:

In the example above, you have two Custom Types, a single type with the id of "home" and name of "Home" and a repeatable type with the id of "post" and the name of "Blog Post".

The value field corresponds to the file name in the custom_types folder with the JSON of the Custom Types.

The command we'll create afterward will automatically create these Custom Types in the user's new Prismic repository when installing your theme.

Once you’ve put the finishing touches on your project code, make it available online. The easiest way to do this is by hosting your project on Github. You'll use the Github URL to build the theme command.

A theme command is structured prismic theme --theme-url <theme-url>. The --conf option specified the path for the configuration file.

Alternatively, you can use --ignore-conf if you don't want the CLI to update the API endpoint. Although then you must specify an endpoint manually.

Take our Next.js blog sample project as an example. We'll replace <github_repository_url> with the link to the project in Github, and <path_to_config_file> with our prismic-configuration.js file. Then, our theme command will look like this:

We recommend you use the README file of your project to document how to run the theme. In particular, the README should include the theme command that we just described.

And that’s it; now you have a Theme that can use by following the steps in "How to use themes," above.