Creating GatsbyJS theme

Note about how to make theme for GatsbyJS

make folder

mkdir gatsby-<name>-theme-workspace && cd <gatsby-your-new-theme>

initialize npm/Yarn new project

yarn init

in package.json:

    "private": true,
    "workspaces": [
        "example", // example of the gatsby website that will use theme
        "gatsby-<name>-theme" // folder where is your theme is located

setup theme folder

cd gatsby-<name>-theme
yarn init

setup example website folder

cd ../example
yarn init

private: true

check yarn workspaces:

yarn workspaces info

should return smth like:

  "example": {
    "location": "example",
    "workspaceDependencies": [],
    "mismatchedWorkspaceDependencies": []
  "gatsby-<name>-theme": {
    "location": "gatsby-<name>-theme",
    "workspaceDependencies": [],
    "mismatchedWorkspaceDependencies": []

add dependencies in example:

yarn workspace example add gatsby

add package of our theme as a dependency:

yarn workspace example add "gatsby-craeft-dev-theme@*"

add scripts section in example/package.json:

    "scripts": {
        "develop": "gatsby develop",
        "build": "gatsby build"

install gatsby, react, react-dom in our theme as a dev and peer dependency:

yarn workspace gatsby-craeft-dev-theme add gatsby react react-dom -D
yarn workspace gatsby-craeft-dev-theme add gatsby react react-dom -P

and add react, react-dom in example as dependencies:

yarn workspace example add react react-dom


create and set layout component

layout component is a component that wraps all your content (pages, posts)

you can create this component in src/components/layout.tsx

you need to set path to this component in gatsby-config.js:

    resolve: \`gatsby-plugin-mdx\`,
    options: {
        defaultLayouts: {
            default: require.resolve("./src/components/layout.tsx"),


My name is Max, also known as @mxkvl.

I am a software developer, currently working mostly with TypeScript, React and Node ecosystems.

I write a blog about topics that interest me most: programming languages in general, TypeScript, testing, writing and other great stuff.

Join the Mailing List