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.

# 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`) to 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

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.

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

References

• Setting up Your Local Dev Environment
• Debugging the Build Process
• Adding Markdown Pages
• gatsby-dev-cli Usage Example
• Configuring a Remote for a Fork
• Syncing a Fork

More Posts

• Routing an External Registered Apex Domain to an AWS S3 Bucket
• Welcome