Using a Gatsby Theme

Gatsby themes let you decompose a site into logical units. Like component libraries, they are an abstraction that allows one team to own and release a package that is pulled into one, or several, separate websites. For example, a team could own a product page theme which is used on multiple e-commerce websites. Other teams might own a blog theme, homepage theme,or store theme, all as separate packages. Themes allow your Gatsby site architecture to match your team structure.

While you can get started quickly with a Gatsby theme starter, you can also install a Gatsby theme directly to an existing Gatsby site. Gatsby themes are plugins, so you can install and use them like any other Gatsby plugin.

Installing a Theme

Like any Gatsby plugin, Gatsby themes are Node.js packages, so you can install them like other published packages in Node using npm or yarn, including local workspaces.

For example, gatsby-theme-blog is the official Gatsby theme for creating a blog.

To install it, run in the root of your site:

Theme options

Depending on the theme, there may be theme options that can be configured via gatsby-config.js.

For example, gatsby-theme-blog can take a number of different options. All of them are documented in the theme’s README file.

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

Published Themes

Public Gatsby themes are published on npm for anyone to use. You can also publish private themes for use by your organization. Examples of private theme package hosting include the npm registry and GitHub Package Registry.

Using Yarn Workspaces

If you would like to work with unpublished themes, consider setting up Yarn Workspaces for theme development and using Yarn instead of npm.

Additional Reading

Start building today on Netlify!

Edit this page on GitHub