Creating a Transformer Plugin
There are two types of plugins that work within Gatsby’s data system, “source” and “transformer” plugins.
- Source plugins “source” data from remote or local locations into what Gatsby calls nodes.
- Transformer plugins “transform” data provided by source plugins into new nodes and/or node fields.
The purpose of this doc is to:
- Define what a Gatsby transformer plugin is, and
- Walk through a simplified reimplementation of an existing plugin, to demonstrate how to create a transformer plugin.
For a step-by-step process, check out the tutorial on Creating a Remark Transformer Plugin.
Transformer plugins “transform” data of one type into another type. You’ll often use both source plugins and transformer plugins in your Gatsby sites.
This loose coupling between the data source and transformer plugins allow Gatsby developers to quickly assemble complex data transformation pipelines with little work.
Just like a source plugin, a transformer plugin is a normal NPM package. It has a
package.json file with optional dependencies as well as a
gatsby-node.js file where you implement Gatsby’s Node.js APIs.
Check out this example of rebuilding a simplified
gatsby-transformer-yaml directly in a site. Say you have a default Gatsby starter site which includes a
gatsby-config.js, use the
gatsby-source-filesystem plugin to create File nodes.
These are exposed in your graphql schema which you can query:
Now you have a
File node to work with:
Now, transform the newly created
File nodes by hooking into the
onCreateNode API in
If you’re following along in an example project, install the following packages:
Parsed YAML content:
Now you’ll write a helper function to transform the parsed YAML content into new Gatsby nodes:
Above, you create a
yamlNode object with the shape expected by the
You then create a link between the parent node (file) and the child node (yaml content).
In your updated
gatsby-node.js, you’ll then iterate through the parsed YAML content, using the helper function to transform each into a new node:
Now you can query for your new nodes containing our transformed YAML data:
Check out the full source code of
Sometimes transforming properties costs time and resources. In order to avoid recreating these properties at each run, you can profit from the global cache mechanism Gatsby provides.
Cache keys should at least contain the contentDigest of the concerned node. For example, the
gatsby-transformer-remark uses the following cache key for the html node:
Accessing and setting content in the cache is as simple as:
- Tutorial: Creating a Remark Transformer Plugin