Optimizing your experience
Gradient background

How I got started with my first Gatsby source & remark plugin

Clarice Bouwer

Software Engineering Team Lead and Director of Cloudsure

Saturday, 2 May 2020 · Estimated 2 minute read

I created my first npm package - EVER! 🎉 It's a Gatsby source and transformer remark plugin called gatsby-remark-interactive-gifs. What that means is that it both extends the Gatsby GraphQL schema with what I call interactive gif data and it translates the Markdown, which I have in the form of a gif protocol, into HTML. That means that this


becomes 👇


If you like the idea of this plugin then please give it a star ⭐ on GitHub. Fork it to get an idea of how I developed the plugin. Try it out by installing it now 😄 npm i -S gatsby-remark-interactive-gifs

Get started

If you are unfamiliar with Gatsby, Gatsby is a blazing fast 🚀 modern site generator for React. To dive right in, check out the Gatsby quick start guide.

  1. Create a Gatsby project (or use your existing one). Use the default or go fancy with a Gatsby starter for a fresh copy. I used gatsby-started-default for my blog.
gatsby new my-default-starter https://github.com/gatsbyjs/gatsby-starter-default
  1. Create a plugins directory in the root of your project with a directory of the plugin you want to create. eg. plugins/gatsby-remark-interactive-gifs There is a specific naming convention for plugins that you should take note of.

  2. Initialize the directory with git before getting started: git init

  3. Each plugin needs to have a package.json file so initialize your plugin with npm init. Add the --yes / -y flag if you wish to skip the questionnaire. Be sure to configure your package.json file with the relevant details if you intend on publishing to npm. Include relevant keywords so that your plugin is automatically detected by Gatsby's indexing.

  4. Install the packages you need for your plugin using npm or yarn and configure them accordingly. Commit your lock file!

  5. Find a place to put your tests. I put mine in a specs directory in the root of the plugin.

  6. Create a src directory in the root of your project where you will place all the files you want to create for your plugin. Read through the plugin documentation to get an idea of what you can create. Also, there are some files that Gatsby looks for in a plugin.

  7. Configure your plugin in your gatsby-config.json file in the root of your project.

  8. Write the code you want to put in your plugin. You are now able to test it locally.

Publish your package

  1. You can create a release script that will bump the version, update the CHANGELOG.md and tag that commit for your release. I use standard-version to automate that process.

  2. To publish your plugin, login to npm through the CLI and then publish it. Be sure to bump your version on each release.

npm run release #if you have the relevant release script
git push -u origin --tags
npm publish
  1. Your plugin may not be available right away. Gatsby uses Algolia to index plugins and Gatsby rebuilds their website periodically to include plugins.