…sound familiar? I imagine for many it will, and I’m no stranger to Googling “Gatsby plugin x not working” myself
But all is not lost! I know where you’re coming from and understand the frustration, so here’s my top tips that might make using Gatsby plugins a little more palatable.
In this post I’ll be discussing the following.
- Things to check before you install a plugin
- Why plugins error
- Contributing to plugins
- When to plug in
Things to check before you install a plugin
Starting at the beginning before you go ahead and install a plugin take some time to have a look at the repository on E.g GitHub and check for the following things.
Is it an official Gatsby plugin?
The quickest way to determine who authored the plugin is to look for the user name in E.g GitHub. Gatsby’s GitHub user name is gatsbyjs. If the username isn’t gatsbyjs then Gatsby didn’t athour the plugin, don’t maintain the plugin and can’t guarantee it’ll work with the current version, or any version Gatsby.
We directly maintain 109 plugins which can be found within the Gatsby repo all of these are maintained with care so you can be assured of a good experience when using one of these.
Here’s some examples of official Gatsby plugins.
You can also see official plugins on the Gatsby Plugin Library page. Plugins that have been authored and are maintained by Gatsby are denoted by the gray monogram “G” logo and the word Official.
Is it a vendor plugin?
Vendor plugins are plugins that are officially maintained by the direct content source or provider. As an example, Prismic and Contentstack both directly maintain and make improvements to their Gatsby Source plugins below:
Is it a community plugin?
Some community plugins are in fact my favourite kind of plugins and are well maintained by some really really dedicated folks. But be mindful, often community plugins are maintained by people in their spare time so if you run into problems you may not get a speedy response.
Here’s some examples of community plugins.
When was the last time it was updated?
This one’s quite important as it gives you some clues as to why the plugin isn’t working as expected. Look at the commits or the timestamp for each file to see when it was last updated. Plugins that were last updated a year ago may well be very out of date and in need of some love. Also watch out for plugins from archived repositories, this is usually a good indication that the author no longer maintains the plugin.
Here’s some examples of archived, or plugins that haven’t been updated in a while… and oops, they’re mine!
What version of Gatsby is defined in the peer dependencies?
As with many open source projects it’s important to list the project’s peer dependencies in the package.json. These are the versions of other projects the plugin relies upon to work correctly. If a project defines "gatsby" : "2.0.0" as a peer dependency there’s a good chance it won’t work as expected with the latest Gatsby version.
Here’s some examples of plugins that have defined the peer dependency version in package.json.
Does it even have peer dependencies?
If the plugin doesn’t define a Gatsby version as a peer dependency it’s quite difficult to work out which version of Gatsby it was designed to work with, as with the timestamp tip above if the plugin doesn’t list Gatsby in the peerDependencies you may well experience errors when you use it.
How many stars does it have?
To be fair this doesn’t really count for much but it goes some way to suggest the plugin has been around a while, is well maintained, provides a good experience for it’s users and will likely work as expected.
How many contributors does it have?
As with the stars this isn’t necessarily an important factor but it may give you some confidence before installing to know there are, and have been contributions to this project which would suggest the author is doing a good job reviewing and accepting changes made to the plugin by the community.
Why do plugins error?
Good question and I suppose the answer is the same as it would be for any npm package that errors. In open source everything is built on top of something else. In the case of Gatsby plugins, and perhaps a good example would be the source plugins, they rely on an API for a specific CMS. If that CMS changes it’s API there’s a chance the plugin will error because the API it’s connecting to reponds with an error. Whilst plugins that are well maintained tend to catch these kinds of changes quite quickly there are often times when a fix has yet to be implemented. It’s here where you can help, opening an issue on the repository notifies the maintainer there’s a problem, and with a bit of luck it’ll be resolved in good time.
Contributing to Plugins
This is the real joy of the Gatsby plugin ecosystem and if you do run into issues you can fix them yourself! — and if i may paraphrase JFK: “Ask not what a plugin can do for you, ask what you can do for a plugin”
Most plugins will have a CODE_OF_CONDUCT and/or CONTRIBUTING file in the repository which will guide you through how to get involved. Take some time to read through these to ensure you’re being as helpful as you can be, and then go ahead and be part of a wonderful community of folks like you that just wanna get s*** done.
When to plug in?
After choosing to use a plugin you’ll undoubtedly see the benefits right away, using source plugins as an example you can let the plugin do the lion’s share of the work, leaving you more time to focus on other areas of your build. Source plugins really come into their own when you have multiple data sources, Shopify for products, Contentful for blog posts or local files for any kind of data and with plugin’s all these differing sourcing methods are somewhat abstracted away allowing you to query data from multiple sources in the same consistent manner via GraphQL.
That said there’s no harm in rolling your own solution. All of the official or community plugins will make use of one or several of Gatsby’s API’s and if you are trying to achieve something and a plugin either errors or perhaps doesn’t yet exist you can code your own solution using similar or the same methods used by plugins.
An example…
To give you one example of this. If you run into problems using a source plugin take a look at how it works.
Source plugins for instance… absolutely all of them will use the same Gatsby Node extension point. It’s called sourceNodes and will be found in a file called gatsby-node.js at the root of the project.
The Gatsby docs explain that this method is an “extension point to tell plugins to source nodes”. But, you can use this method in your own project, even if it’s not a plugin!
…and in case sourceNodes is a bit confusing, it means: The point during the Gatsby build process where you can make an HTTP request to a remote API that fetches some data and can then pump the response into Gatsby’s data layer using createNode.
In the coming weeks i’ll be working on creating a few posts about sourcing data but in the meantime, if you’re interested, here’s a blog post that explains how sourceNodes works: https://paulie.dev/posts/2021/07/gatsby-source-nodes/
Give me, @PaulieScanlon or @GatsbyJS a follow on Twitter and we’ll be Tweeting soon about ways in which you can source data from absolutely anywhere for use in your Gatsby project.
See you around!
Paul 🕺