Recipes: Working with Themes

A Gatsby theme abstracts Gatsby configuration (shared functionality, data sourcing, design) into an installable package. This means that the configuration and functionality isn’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another.

Creating a new site using a theme

Found a theme you’d like to use on your project? Awesome! You can configure it for use by following the steps below.

If you’d like to take a look at more theme options, check out this list of themes.

Prerequisites

• Make sure you have the Gatsby CLI installed

Directions

1. Create a gatsby site

2. Change directory and install theme

In this example, our theme is gatsby-theme-blog. You can replace that reference with whatever your theme is named.

3. Add theme to gatsby-config.js

Follow the instructions found in the README of the theme you’re using to determine what configuration it requires.

To learn how to further customize the blog theme, check out the available configuration options in the Gatsby-theme-blog Documentation.

4. Run gatsby develop, the theme should now be running on your site. In this case with the blog theme configured with the basePath to "/blog", it should be available at http://localhost:8000/blog.

Additional resources

• To learn how to further customize a theme, check out the docs on Gatsby theme shadowing.

• You can also use multiple themes on a project.

Creating a new site using a theme starter

Creating a site based on a starter that configures a theme follows the same process as creating a site based on a starter that doesn’t configure a theme. In this example you can use the starter for creating a new site that uses the official Gatsby blog theme.

Prerequisites

• Make sure you have the Gatsby CLI installed

Directions

1. Generate a new site based on the blog theme starter:

2. Run your new site:

Additional resources

• Learn how to use an existing Gatsby theme in the shorter conceptual guide or the more detailed step-by-step tutorial.

Building a new theme

Video hosted on egghead.io.

Prerequisites

• The Gatsby CLI installed
• Yarn installed

Directions

1. Generate a new theme workspace using the Gatsby theme workspace starter:

2. Run the example site in the workspace:

Additional resources

• Follow a more detailed guide on using the Gatsby theme workspace starter.
• Learn how to build your own theme in the Gatsby Theme Authoring video course on Egghead, or in the video course’s complementary written tutorial companion.