How to Contribute to the Gatsby Repository
Tags: gatsby, opensource, jamstack, tutorial
Published: 2020-03-18 18:29:09

#### 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](https://en.wikipedia.org/wiki/Monorepo) managed with [Lerna](https://lerna.js.org/).

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](https://jamstack.org/). I would even say, one of their flagships.

The [source code lives on Github](https://github.com/gatsbyjs/gatsby) 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](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).

_The Gatsby project itself, all his packages, and the contributors documentation use Yarn as the package manager ([find out how to install Yarn](https://classic.yarnpkg.com/en/docs/install/))._

Clone the forked repo to your local machine.

```bash
# 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.

```bash
# 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.

```bash
# 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`.

```javascript
// 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.

```bash
# 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`.

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

Add configuration to `gatsby-config.js`.

```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`.

```bash
gatsby develop
```

You should see the `HELLO_GATSBY_DEVELOPMENT` in the terminal.

![Gatsby CLI develop command output](https://dev-to-uploads.s3.amazonaws.com/i/2hmkt9yiw5m345wqoivm.png)

**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](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

You got questions or want to start a conversation? Contact me on [Twitter](https://twitter.com/rbelow_) or [GitHub](https://github.com/rbelow)!

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

```bash
# 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`.

```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](https://github.com/guard/listen/wiki/Increasing-the-amount-of-inotify-watchers)

---

Kudos for learning with this tutorial.

**_Follow me on [GitHub](https://github.com/rbelow) or [Twitter]._**

[twitter]: https://twitter.com/rbelow_ 'Twitter'

_If for some casual the indications did not work for you; [drop me a line with the infringing points](mailto:hello@rubenbelow.com?subject=Infringing%20Point). 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](https://www.gatsbyjs.org/contributing/setting-up-your-local-dev-environment/#add-tests)
- [Debugging the Build Process](https://www.gatsbyjs.org/docs/debugging-the-build-process/#chrome-devtools-for-node)
- [Adding Markdown Pages](https://www.gatsbyjs.org/docs/adding-markdown-pages/)
- [gatsby-dev-cli Usage Example](https://www.youtube.com/watch?v=D0SwX1MSuas)
- [Configuring a Remote for a Fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork)
- [Syncing a Fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)

## More Posts

- [Routing an External Registered Apex Domain to an AWS S3 Bucket](https://rubenbelow.com/posts/third-party-apex-domain-aws-s3-static-website-routing/)
- [Welcome](https://rubenbelow.com/posts/welcome/)