As methodologies for building Gatsby Themes begin to formalize and standardize, documentation will be added here. These aren’t intended to be the only way to solve things, but are recommended approaches. If you have other ideas and best practices please open up a PR to update this page.
It’s required to prefix themes with
gatsby-theme-. So if you’d like to name your theme “awesome” you
can name it
gatsby-theme-awesome and place that as the
name key in your
package.json. Prefixing themes with
gatsby-theme- enables Gatsby in identifying theme packages for compilation.
Initializing required directories
If your theme relies on the presence of particular directories, like
gatsby-source-filesystem, you can use the
onPreBootstrap hook to initialize them to avoid a crash when Gatsby tries to build the site.
Separating queries and presentational components
As a theme author, it’s preferable to separate your data gathering and the components that render the data. This makes it easier for end users to be able to shadow a component like
AuthorCard without having to write a page query or static query.
You can use a template for top-level data collection with a page query that passes the data to a
You can use static queries at the top level template as well and pass the data to other presentational components as props:
For commonly customized things, such as site title and social media handles, you can have the user set site metadata in their
gatsby-config.js. Then, throughout your theme you can create a static query to access it:
Then use it in components like a header:
Since themes will typically be installed by an end user from npm, it’s important to follow semantic versioning, commonly referred to as semver.
This will allow your users to quickly discern how a dependency update might affect them. Patches and minor versions are not considered breaking changes, major versions are.
Patches are defined as bug fixes that are done in a backwards-compatible way. This means that public facing APIs are unaffected.
Examples of patch versions
- Fixing a bug in a component, such as fixing a warning or adding a fallback value.
- Upgrading dependencies to their latest minor and patch versions.
Minor versions are defined as new features or functionality that are added in a backwards-compatible way. This means that existing public facing APIs are unaffected.
Examples of minor versions
- Adding new pages or queries to your theme. For example, adding tag pages to a blog.
- Adding new configuration options to further customize a theme.
- Displaying additional data such as displaying excerpts to a post list.
- Adding additional props to a component for new functionality.
- Adding a new MDX shortcode that users can opt into.
Major versions are any bugfixes or new features that have been added without full backwards-compatibility. These are often called “breaking changes”.
These changes should be accompanied by a migration guide that users can follow along for performing a theme upgrade.
Examples of major versions
- Changing a filename in
srcwill always be a breaking change due to shadowing.
- Moving where a query occurs
- Renaming a component
- Renaming a directory
- Removing or changing the props a component accepts since it will affect component extending.
- Changing queries since a user could be using the original data in shadowed components.
- Removing or changing the behavior of your theme’s configuration.
- Removing attributes in schema definitions because it can break end user queries.
- Removing default data this could change your generated schema and break a user’s site if they depend on some part of that generated schema.
- Changing plugins or plugin configuration such as removing a remark plugin as it will change the behavior of MD/MDX rendering.