Converting a Starter to a Theme
Gatsby themes are designed to be easy to create from an existing starter. Here we will walk you through the main steps of converting your starter to a theme.
To start converting your starter to a library, get started by updating your
package.json to use the
gatsby-theme-* naming convention. If your starter is
gatsby-starter-awesome-blog you can update the name key to
gatsby-theme-awesome-blog (and double check that it’s available on npm).
devDependencies . It’s preferable to add them as
peerDependencies as well. This helps end users determine which versions they want and npm/yarn will be able to resolve them properly.
In addition to updating your dependencies, you will need to create an
index.js file in the root of your project. This allows Gatsby to resolve the theme since Node automatically looks for
One of the key differences between themes and starters is that a theme is no longer executed when the Gatsby CLI is being run since it’s now a dependency. This often results in errors sourcing content and finding templates since they will look in the end user’s directory.
In order to fix this, consider the following code that works as a starter:
path.resolve is being used the starter will resolve
src/templates/post.js rather than
node_modules/gatsby-theme-awesome-blog/src/templates/post.js. In order to fix this you can use
require.resolve which will look relative to the theme so the correct template is found.
There may be other locations where you will need to update the path resolution like your
gatsby-config.js as well.
If your theme provides pages for things like the blog post index and a homepage, you will need to source them.
Gatsby will only look in the relative
src/pages directory when
gatsby develop is run.
You will need to use the
Then, tell the plugin to look in your theme’s
In order to allow others to install your theme you will need to publish it to npm. If this is new for you, learn how to publish to npm.
From the root of your newly created theme run
Once you’ve published, you can install the theme in your starter.
Edit this page on GitHub