Skip to main content

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 list of themes.


Make sure you have the following installed:


  1. Create a gatsby site
  1. 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.

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

  1. Run yarn develop , the theme should be avaliable at http://localhost:8000/{basePath}

To learn how to further customize a theme,check out the avaliabe paths on Gatsby-theme-blog Documentation.

Additional resources

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.



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

Additional resources

Building a new theme

Video hosted on



  1. Generate a new theme workspace using the Gatsby theme workspace starter:
  1. Run the example site in the workspace:

Additional resources

Edit this page on GitHub