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 removenode_modules
, andpackage-lock.json
and donpm 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:
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
Top comments (0)