Code Contributions

The beauty of contributing to open source is that you can clone your favorite project, get it running locally, and test out experiments and changes in real time! Way to feel like a wizard.

Repo setup

This page includes details specific to the Gatsby core and ecosystem codebase.

To start setting up the Gatsby repo on your machine using git, Yarn and Gatsby-CLI, check out the page on setting up your local dev environment.

Alternatively, you can skip the local setup and use an online dev environment.

To contribute to the blog, check out the setup steps on the blog contributions page. For instructions on contributing to the docs, visit the docs contributions page.

Creating your own plugins and loaders

If you create a loader or plugin, we would love for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for plugins and the API specification.

Contributing example sites

Gatsby’s policy is that “Using” example sites (like those in the examples part of the repo) should only be around plugins that are maintained by the core team as it’s hard to keep things up to date otherwise.

To contribute example sites, it is recommended to create your own GitHub repo and link to it from your source plugin, etc.

Using Docker to set up test environments

With all of the possible Gatsby integrations, it might help to spin up a Docker container with the software application you need to test. This makes installation a breeze, so you can focus less on getting set up and more on the integration details that matter to you.

Do you have a setup not listed here? Let us know by adding it to this file and opening a PR.

Docker, WordPress and Gatsby

To install WordPress to use with Gatsby, this docker-compose.yml file will come in handy:

Use the above file contents when following the Docker WordPress install instructions:

Using Docker Compose, you can start and stop a WordPress instance and integrate it with the Gatsby WordPress source plugin.

Development tools

Debugging the build process

Check Debugging the build process page to learn how to debug Gatsby.

Official theme development

This section is for official theme development. If you are looking to build your own theme, see building themes.

Themes live in their own repo. The themes themselves live in the packages directory and starters using them are in the starters directory. In order to work on a theme, find the starter that uses it and do the following:

  1. Run yarn in your terminal in the root of the repo.
  2. Still in the repo root, run yarn workspace <starter name> develop.

From there, you can make changes in the theme and see them reflected in the running site.


At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can open an issue on GitHub. Or drop in to our Discord server for general community discussion and support.