Pixabay Image Source Plugin Tutorial

Creating your own source plugin.

What this tutorial covers

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.

What is a source plugin?

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

Why create a source plugin?

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.

How to create a source plugin

Overview

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.

NOTE: You’ll need a Pixabay API key which you can get by registering for a Pixabay account. Your API key is in the “Search Images“ section of the Pixabay API docs.

An example API request

Pixabay’s API documentation describes how their API works. Here’s an example that uses a few options to search for photos:

https://pixabay.com/api/?q=yellow+flowers&editors_choice=true&pretty=true&key=<YOUR_API_KEY_HERE>

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.

Plugin behavior

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

Setup a new Gatsby site

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:

Create a plugins folder

The bare essentials of a plugin are a directory named after your plugin, which contains a package.json file and a gatsby-node.js file:

Start by creating the directory and changing into it:

Create a package.json file

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 --yes if you’d like to specify the options yourself.

Add dependencies

You’ll use a couple of modules from npm to add some helper functionality. Install them with:

Open your package.json file and you’ll see node-fetch and 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 gatsby-node.js file

Create a new file called gatsby-node.js in your gatsby-source-pixabay directory, and add the following:

Step by step through your gatsby-node.js file

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:

Add the plugin to your site

The skeleton of your plugin is in place which means you can now add it to your project and check your progress so far.

Open gatsby-config.js from the root directory of your tutorial site, and add the gatsby-source-pixabay plugin:

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 gatsby-config.js file:

Note that Gatsby is warning that your plugin doesn’t do anything yet. Time to fix that.

Fetch remote data from Pixabay

Update gatsby-node.js in your plugins/gatsby-source-pixabay/ directory:

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.

Use createNode function

You’re adding a helper function on lines 13 to 28 and processing the data into a node on lines 46 to 49:

Query for results

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:

Or open the query from this link.

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.

Publishing a plugin

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.json file 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.

Summary

You’ve written a local Gatsby plugin that:

• can be configured with an entry in your gatsby-config.js file
• requests data from a third-party API
• pulls the API data into Gatsby’s node system
• allows the data to be queried with GraphQL

Congratulations!

Where next?

Your plugin has been adapted from Jason Lengstorf’s gatsby-source-pixabay plugin. Check out the source on GitHub.

Try adding new features to your plugin, for example - download images from Pixabay, improve error handling, add documentation or automated tests.

Check out Gatsby’s docs on plugin authoring and creating a source plugin.

A note on JavaScript versions

In this tutorial you’ve written code in a version of JavaScript that’s compatible with Node.js version 6 and above.

Jason’s version of the plugin uses newer JavaScript features with babel to provide compatibility for older versions of Node. Compare your code with Jason’s to see how newer JavaScript features allow for more succinct code.