This article shows you what you need to do to create a theme and what a user needs to do to launch it.
What is a theme, anyway?
A theme is a set of project files that helps someone get a website up and running quickly. The theme provides everything needed to get started: the website app, prismic.io custom types, templates, and styles.
Once a theme is available, a user can install the theme using the prismic command line tool and everything is set up automatically for them. Including the custom types in their prismic.io repository! Then all they need to do is fill in some content and launch the website.
Creating a theme for Prismic
Let’s walk through the steps you need to take to create a theme for prismic.io.
The easiest way to get started is to create a clone of the nodejs prismic sdk. From here you can build out the theme, with all the templates and styles.
Include a Prismic configuration file
You can also choose to build your theme from scratch if you want. If you do this, you need to make sure to include a prismic-configuration.js file in the root folder of the project. This file needs to at least have the API endpoint configuration as shown below.
This is needed so that the prismic command line tool can automatically update the API endpoint with the user’s prismic repository url.
Add Custom Types
The next thing you need to do is to include the custom types for your theme.
Start by creating a folder named "custom_types" in the root folder of the project. Inside this folder, create a json file for each custom type that you need for your theme.
The prismic command line tool will automatically create these custom types in the user's prismic repository when installing your theme. Use the exact same format used to create the custom types in the prismic.io dashboard.
NOTE: You can only add 20 custom types maximum with the CLI Themes.
Next you'll need to create an "index.json" file in the custom_types folder. It will contain the metadata for each of the custom types included in the project. Use the following format:
"name": "Blog Home",
"name": "Blog Post",
In the example above you have two custom types, a single custom type with the id "bloghome" and a display name "Blog Home", and another custom type post which is repeatable with the id "post" and the display name "Blog Post".
The field "value" correspond to the file name in the custom_types folder with the actual custom type information.
Include the theme templates and styles
Some things to consider when creating a theme:
- Implement the preview & edit-button functionality
- Include a 404 page (Page not found)
- Prevent the website from crashing with default values if the user doesn’t put anything into a content field
- Don’t forget a Readme file or some sort of instructions to help the user launch the project.
Make your theme available online
Once you’ve put the finishing touches on your theme, you just need to make your theme available online. Compress your project folder into a zip file, and make it available with a public url. Make sure to put the project files at the root of the zip file.
Alternatively, you can host your theme on github and the user can use the github link to launch their theme.
Launching a theme
With your theme available online, actually launching a theme project is really easy!
The first step is to download the prismic command line tool. From the terminal run the following command to install the tool globally on your computer:
npm install -g prismic-cli
With this installed, you will need to run the 'prismic theme' command. To use this command you will need to specify the location of the configuration file so the CLI can update the API endpoint.
To specify the config file location:
prismic theme http://example.com/your-theme-url.zip --conf path/to/file
Alternatively you can ignore the the configuration file step. Although then you must update the configuration file manually.
To ignore the config file step
prismic theme http://example.com/your-theme-url.zip --ignore-conf
Now the theme will be downloaded, a prismic repository will be set up, the api endpoint will be updated, and the custom types will be created.
And that’s all there is to it, the user’s project will be set up automatically! All they will need to do is add some content in their repository and start the website app.
If you want to see a Prismic theme in action, check out this sample theme for a simple website.
When you create a theme for Prismic, please share your project with us! We always love to see your wonderful creations.