Create and Use 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 brand new repository with Custom Types

Use a theme

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. For instance, you could use themes to launch a project demo to present to a work team, a client, or in a programming course.

Before you run the theme command, install the prismic-cli:

  • npm
  • Yarn
Copy
npm install -g prismic-cli
Copy
yarn global add prismic-cli

To use a theme, create or find a theme as a git repo or ZIP file.

The README for the theme should include a theme command that looks like this:

Copy
prismic theme --theme-url <github_repository_url>

When you execute 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.

Create a theme

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

Prepare your project code

This can be as complex as you want it to be. If you plan on creating something simple like a boilerplate or quickstart, we recommend you to 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

Add a configuration file

Create a file at the root of the project to add the configuration for the theme. This file can be written in any language or extension file you use in your project as long as it has a field for this repository URL:

'https://your-repo-name.prismic.io/api'

Here are a few config file examples with different file extensions:

  • JavaScript 1
  • JavaScript 2
  • JavaScript 3
  • JSON
  • PHP
Copy
// Example config.js file

export const apiEndpoint = 'https://your-repo-name.cdn.prismic.io/api/v2'
Copy
// Example config.js file

export default {
  prismic: {
    endpoint: "https://your-repo-name.cdn.prismic.io/api/v2"
  }
};
Copy
// Example config.js file

module.exports = {
  apiEndpoint: 'https://your-repo-name.prismic.io/api/v2',
};
Copy
// Example config.json file

{
  "apiEndpoint": "https://your-repo-name.cdn.prismic.io/api/v2",
}
Copy
// Example config.php file

<?php
define('PRISMIC_URL', 'https://your-repo-name.prismic.io/api/v2');
?>

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

Add Custom Types

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 repo, 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:

Copy
[{
  "id": "home",
  "name": "Home",
  "repeatable": false,
  "value": "home.json"
}, {
  "id": "post",
  "name": "Blog Post",
  "repeatable": true,
  "value": "post.json"
}]

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.

Publish the code

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.

Create 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.

  • With config file
  • Without config file
Copy
prismic theme --theme-url <github_repository_url> --conf <path_to_config_file>
Copy
prismic theme --theme-url <github_repository_url> --conf --ignore-conf

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:

Copy
prismic theme --theme-url https://github.com/prismicio/nextjs-blog --conf prismic-configuration.js

Add a README file

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.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.