Creating an Image Source Plugin
In this tutorial you’ll create your own source plugin. Your plugin will source data from pixabay.com allowing you to add Pixabay images to any Gatsby site.
Source plugins “source” data from remote or local locations into what Gatsby calls nodes.
For more background on source plugins, check out Gatsby’s source plugin documentation
Source plugins convert data from any source into a format that can be processed by Gatsby. Your Gatsby site could use several source plugins to combine data in interesting ways.
If you can’t find a plugin for your data source you can create your own.
NOTE: if your data is local i.e. on your file system and part of your site’s repo, then you generally don’t want to create a new source plugin. Instead you want to use gatsby-source-filesystem which handles reading and watching files for you. You can then use transformer plugins like gatsby-transformer-yaml to make queryable data from files.
Your plugin is going to source images from Pixabay. You’ll be able to configure your plugin in your site’s
gatsby-config.js file and write GraphQL queries to access your plugin’s data.
Pixabay’s API documentation describes how their API works. Here’s an example that uses a few options to search for photos:
Take the above URL and paste it into a browser to see Pixabay’s response to your query. It gives you a list of photos matching the query “yellow flowers” that have received an Editor’s Choice award.
NOTE: You should replace
<YOUR_API_KEY_HERE>with your Pixabay API key.
Your plugin will have the following behavior:
- Accept config options like a Pixabay API key and a search query
- Make an API request using the provided config options
- Convert the data in the API response to Gatsby’s node system
Create a new Gatsby project and change directories into the new project you just created.
You’re going to build your plugin as a “local” plugin that only exists for your project. Later on you’ll learn how to publish a plugin to npm so anyone can use it, but for now create a
plugins directory and change into that directory:
The bare essentials of a plugin are a directory named after your plugin, which contains a
package.json file and a
Start by creating the directory and changing into it:
Now create a
package.json file, this describes your plugin and any third-party code it might depend on. npm has a command to create this file for you. Run:
to create the file using default options.
NOTE: You can omit
--yesif you’d like to specify the options yourself.
You’ll use a couple of modules from npm to add some helper functionality. Install them with:
package.json file and you’ll see
query-string have been added to a
dependencies section at the end:
With the setup done, move on to adding the plugin’s functionality.
Create a new file called
gatsby-node.js in your
gatsby-source-pixabay directory, and add the following:
What did you do by adding this code? You started by importing the dependencies that you added earlier (along with one built in dependency):
Then you implemented Gatsby’s
sourceNodes API which Gatsby will run as part of its bootstrap process. Gatsby expects sourceNodes to return either a promise or a callback (3rd parameter). This is important as it tells Gatsby to wait to move on to next stages until your nodes are sourced, ensuring your nodes are created before the schema is generated.
You do some initial setup:
And finally add a placeholder message:
The skeleton of your plugin is in place which means you can now add it to your project and check your progress so far.
gatsby-config.js from the root directory of your tutorial site, and add the
Open a new terminal in the root directory of your tutorial site, then start Gatsby’s development mode:
Check the lines after
success on PreBootstrap, you should see your “Testing my plugin” message along with the
key from your
Note that Gatsby is warning that your plugin doesn’t do anything yet. Time to fix that.
gatsby-node.js in your
You’ve added code that fetches photo data from the Pixabay API. For now, your plugin logs that data but doesn’t do anything else. Check that you can see the logged photo data by restarting
npm run develop. This time you should see a series of results like:
You’re ready to add the final step of your plugin - converting this data into a Gatsby node.
You’re adding a helper function on lines 13 to 28 and processing the data into a node on lines 46 to 49:
Your plugin is ready. Restart
npm run develop and open a browser at
http://localhost:8000/___graphql. The Pixabay data can be queried from here. try:
Experiment with different options in your
gatsby-config.js file to see how that affects your query results. The Pixabay API docs might be a useful reference.
Don’t publish this particular plugin to npm or the Gatsby Plugin Library, because it’s just a sample plugin for the tutorial. However, if you’ve built a local plugin for your project, and want to share it with others, npm allows you to publish your plugins. Check out the npm docs on How to Publish & Update a Package for more info.
NOTE: Once you have published your plugin on npm, don’t forget to edit your plugin’s
package.jsonfile to include info about your plugin. If you’d like to publish a plugin to the Gatsby Plugin Library (please do!), please follow these steps.
You’ve written a local Gatsby plugin that:
- can be configured with an entry in your
- requests data from a third-party API
- pulls the API data into Gatsby’s node system
- allows the data to be queried with GraphQL
Try adding new features to your plugin, for example - download images from Pixabay, improve error handling, add documentation or automated tests.