How to Contribute to the Gatsby Repository

Author profile picture

@rubenbelowRubén Below

rubenbelow.com

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`)
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:

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

More Posts

Previously published at https://rubenbelow.com/posts/contributing-to-the-gatsby-project/

Tags

The Noonification banner

Subscribe to get your daily round-up of top tech stories!