How to Contribute to the Gatsby Repository

Learn how to contribute code to the open source project Gatsby

In Gatsby all projects are packages including Gatsby, plugins, and themes: It's a monorepo managed with Lerna.

At the end of this tutorial, you'll have a working local setup where you can test your changes to a Gatsby package.

Gatsby is one of the favorite static site generators right now. With more than 42.000 GitHub stars it's a major contributor to the Jamstack concept. I would even say, one of their flagships.

The source code lives on Github and everybody is welcome to contribute to the project.

If you encounter some problem while following this tutorial. Take a look
at the troubleshooting section, at the end of this post.

Let's start.

Set Up the Gatsby Project

Go to the Gatsby GitHub project and fork it.

The Gatsby project itself, all his packages, and the contributors documentation use Yarn as the package manager (find out how to install Yarn).

Clone the forked repo to your local machine.

# clone the fork
git clone --depth=1 https://github.com/<your-username>/gatsby.git

# go to gatsby
cd gatsby/

# install and build the projects
yarn run bootstrap

# check if everything works
yarn test

Configure the Git upstream.

# check your current remote configuration
git remote -v

# configure the original gatsby repo as your remote upstream
git remote add upstream https://github.com/gatsbyjs/gatsby.git

# check if the configuration has updated
git remote -v

# download objects and refs from the upstream
git fetch upstream

# integrate the upstream master into your local branch
git merge upstream/master

Create a branch.

# create the branch where you're going to work
git checkout -b <feature-or-bugfix>/<feature-or-bugfix-name>

Create a symlink to a Gatsby package.

# create the branch where you're going to work
git checkout -b <feature-or-bugfix>/<feature-or-bugfix-name>
```

Create a symlink to a Gatsby package.

```bash
# change to the package directory (in this case a gatsby plugin)
cd packages/gatsby-transformer-remark/

# create the global symlink to the package
yarn link

# start watching the package files for changes
yarn watch

Add

console.warn(`HELLO_GATSBY_DEVELOPMENT`)

gatsby-transformer-remark

// in packages/gatsby-transformer-remark/src/on-node-create.js:16

// code...

const { createNode, createParentChildLink } = actions;

// Add the next line before the if:
console.warn(`HELLO_GATSBY_DEVELOPMENT`);

// We only care about markdown content.
if (
  node.internal.mediaType !== `text/markdown` &&
  node.internal.mediaType !== `text/x-markdown`
) {
  return {};
}

// more code...

Set Up a Gatsby Site

Now you're going to set up a Gatsby site as an end-user would do. This will help you to test the changes you're doing to the Gatsby project.

Gatsby CLI generated sites and the Gatsby end-user documentation use npm.

Open a new terminal and create a Gatsby test site.

# install gatsby-cli
npm i -g gatsby-cli

# go back to your workspace directory
cd ../../../

# create a new gatsby site
gatsby new gatsby-test-site

# change directory into site folder
cd gatsby-test-site/

Link the Gatsby plugin inside

gatsby-test-site

# link the local package (the package will not appear in your package.json)
npm link gatsby-transformer-remark

Add configuration to

gatsby-config.js

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      // CommonMark mode (default: true)
      commonmark: true,
      // Footnotes mode (default: true)
      footnotes: true,
      // Pedantic mode (default: true)
      pedantic: true,
      // GitHub Flavored Markdown mode (default: true)
      gfm: true,
      // Plugins configs
      plugins: []
    }
  }
];

Start the

gatsby-test-site

gatsby develop

You should see the

HELLO_GATSBY_DEVELOPMENT

in the terminal.

Congratulations! You have a working Gatsby environment. And you can start contributing to the open source project right now.

Find first-time friendly issues on the Gatsby project issues tab.

You got questions or want to start a conversation? Contact me on Twitter or GitHub!

By the way: don't forget to test and lint the package you're changing.

# from the root of the gatsby repo
yarn jest gatsby-transformer-remark

yarn lint

Happy coding!

Troubleshooting

gatsby develop throws errors

When executing

gatsby develop

on your

gatsby-test-site

throws errors:

Clean up the Gatsby cache with
```
gatsby clean
```
. If the problem persists remove
```
node_modules
```
, and
```
package-lock.json
```
and do
```
npm i
```

To make it easier for the future add a script to your

package.json

{
  "scripts": {
    "clean:npm": "rm -rf ./node_modules/ && rm ./package-lock.json"
  }
}

Error: ENOSPC: System limit for number of file watchers reached

If you get a

System limit for number of file watchers reached

error, while watching files on a Linux distribution:

Increase the file watch limit of your OS

Software Versions

These are the software versions used for this tutorial:

Gatsby: 2.19.32
Gatsby CLI: 2.8.27
gatsby-transformer-remark: 2.6.55
Node.js: 12.16.1
npm: 6.13.4

Kudos for learning with this tutorial.

Follow me on GitHub or Twitter.

If for some casual the indications did not work for you; drop me a line with the infringing points. I'll update the post correspondingly.

References