Written by: Geoffrey Callaghan

how to create a Gatsby theme

How To Create A Gatsby Theme

Creating a Gatsby theme involves several steps, from setting up a Gatsby site to developing the theme itself and finally packaging it for distribution. Here’s a step-by-step guide:


  • Basic knowledge of JavaScript, React, and Gatsby.
  • A development environment with Node.js and npm or Yarn installed.

Step 1: Setting Up Your Environment

  1. Install Gatsby CLI:

    npm install -g gatsby-cli
  2. Create a New Gatsby Site:

    gatsby new my-gatsby-theme
    cd my-gatsby-theme

Step 2: Creating the Theme

  1. Set Up Theme Directory Structure:

    Inside your Gatsby site, create a directory for your theme:

    mkdir themes
    cd themes
    mkdir gatsby-theme-my-theme
    cd gatsby-theme-my-theme
  2. Initialize a New npm Package:

    Initialize your theme as a new npm package:

    npm init

    Fill in the necessary details (name, version, etc.). Use gatsby-theme-my-theme as the package name.

  3. Add Dependencies:

    Install Gatsby and React dependencies:

    npm install gatsby react react-dom

Step 3: Developing the Theme

  1. Create a Gatsby Config File:

    Create a gatsby-config.js file for your theme:

    // themes/gatsby-theme-my-theme/gatsby-config.js
    module.exports = {
      plugins: [],
  2. Create Theme Components:

    Set up the basic structure for your theme components:

    mkdir src
    mkdir src/components
    mkdir src/templates

    Add a simple component:

    // themes/gatsby-theme-my-theme/src/components/Header.js
    import React from 'react';
    const Header = () => (
        <h1>My Gatsby Theme</h1>
    export default Header;
  3. Create a Layout Component:

    Add a layout component that includes the header:

    // themes/gatsby-theme-my-theme/src/components/Layout.js
    import React from 'react';
    import Header from './Header';
    const Layout = ({ children }) => (
        <Header />
    export default Layout;
  4. Create a Page Template:

    Create a template for pages that use your theme:

    // themes/gatsby-theme-my-theme/src/templates/page.js
    import React from 'react';
    import Layout from '../components/Layout';
    const PageTemplate = ({ pageContext }) => (
    export default PageTemplate;

Step 4: Using the Theme in a Site

  1. Create a New Gatsby Site:

    Go back to your root directory and create a new Gatsby site that uses your theme:

    gatsby new my-theme-site
    cd my-theme-site
  2. Install Your Theme:

    Link your theme for local development:

    npm install ../themes/gatsby-theme-my-theme

    Add your theme to the site’s gatsby-config.js:

    // my-theme-site/gatsby-config.js
    module.exports = {
      plugins: [
  3. Create Pages Using the Theme:

    Create a gatsby-node.js file to programmatically create pages:

    // my-theme-site/gatsby-node.js
    exports.createPages = ({ actions }) => {
      const { createPage } = actions;
        path: '/about',
        component: require.resolve('gatsby-theme-my-theme/src/templates/page.js'),
        context: {
          title: 'About Us',
          content: 'This is the about page content.',

Step 5: Publishing the Theme

  1. Prepare for Publication:

    Add a package.json script for building:

    "scripts": {
      "build": "gatsby build"
  2. Publish to npm:

    If you haven’t already, log in to npm:

    npm login

    Publish your theme:

    npm publish

Step 6: Using the Published Theme

  1. Install the Published Theme:

    In any new Gatsby site, you can now install and use your published theme:

    npm install gatsby-theme-my-theme
  2. Configure the Site to Use the Theme:

    // gatsby-config.js
    module.exports = {
      plugins: [

Final Steps

  1. Test Your Theme:

    Thoroughly test your theme to ensure it works as expected in different Gatsby sites.

  2. Document Your Theme:

    Provide clear documentation on how to use and customize your theme in the README.md file.

By following these steps, you can create, develop, and publish a Gatsby theme, making it reusable for various Gatsby projects.