Gatsby Plugin - JSON Output
Fetch JSON content from Gatsby with API-like static feeds that automatically update with your builds.
- Can create individual JSON view of each generated static HTML file. For example:
/about/index.html
would also have a/about/index.json
- Can create a set of JSON feed files
Contents
Install
With NPM:
npm install gatsby-plugin-json-output
With Yarn:
yarn add gatsby-plugin-json-output
Usage
Setup requires the following being added to your gatsby-config.js
like below:
// gatsby-config.jsconst siteUrl = `https://example.com`plugins: resolve: `gatsby-plugin-json-output` options: siteUrl: siteUrl // defined on top of plugins graphQLQuery: ` { allMarkdownRemark(limit: 1000) { edges { node { excerpt html fields { path } frontmatter { title created updated } } } } } ` resultsdataallMarkdownRemarkedges feedMeta: author: name: author description: siteDescription favicon: `/icons/icon-48x48.png` title: siteTitle resultsdataallMarkdownRemarkedges feedFilename: "exampleFeedFilename" nodesPerFeedFile: 100 ;
siteUrl
(required)
This should be a string of your site's URL.
graphQLQuery
(required)
This needs to be a Gatsby GraphQL query string, that you would pass to graphql()
. The result of this query must be an array of objects including the path/slug to each static HTML page and the contents you will use to serialize into a JSON file.
For example, if I wanted to create a JSON file for each of the pages created using gatsby-transformer-remark, then I might use a query like:
{ edges node html fields path frontmatter title created updated }
The fields { path }
object having been created by something like gatsby-source-filesystem/#createfilepath.
serialize
(optional)
Provide if you want to create individaul JSON files for each node.
This plugin uses this serialize function to structure the contents of the individual JSON files. You can use this function to restructure the nested nature of graphQLQuery
. This plugin will pass the results object of the graphQLQuery
to your serialize
function.
This function must return an array of objects with any structure you'd like your JSON files to be.
The only required field is path
- which must be the relative path from the root of public
(Gatsby's build output folder) of each static HTML file, like /about
or /blog/post-1
etc.
For the example graphQLQuery
above, you might provide a function like:
// Using arrow functions resultsdataallMarkdownRemarkedges; // Or traditional functions { var nodes = ; for var i = 0; i < resultsdataallMarkdownRemarkedgeslength; i++ var node = resultsdataallMarkdownRemarkedgesinode; nodes; return nodes; }
feedMeta (optional)
Provide this to include meta into the JSON feed files. This is an optional object, and can be any key-pair shape. A standard feed meta object might be something like:
feedMeta: author: name: "Ex Ample" description: "Read all the example blog posts from Ex Ample." favicon: `https://example.com/icons/icon-48x48.png` title: "Ex Ample's Blog"
serializeFeed
(optional)
Include this if you want to create JSON feed files. If you want to create multiple feed files, add multiple gatsby-plugin-json-output
objects to gatsby-config.js
, specify a name using the feedFilename
field. This is useful if you want to provide feeds with different JSON structures or different data via GraphQL.
This plugin uses this serializeFeed function to structure the contents of the JSON feed files. You can use this function to restructure the nested nature of graphQLQuery
. This plugin will pass the results object of the graphQLQuery
to your serializeFeed
function.
This function must return an array of objects with any structure you'd like your JSON feed files to be.
For the example graphQLQuery
above, you might provide a function like:
// Using arrow functions resultsdataallMarkdownRemarkedges
Or, a traditional function like the example in the (serialize)[#serialize] section.
You will find the feed files in the built assets starting from public/feed-1.json
, then public/feed-2.json
(etc) as required for the number of posts. For the feedMata
object and serialiseFeed
function examples above you would get a JSON feed files in a format like:
feedFilename
(optional)
Default name is feed
followed by the page number. Example: feed-1.json
.
Use this option to set the name of the feed file. This is useful if you want to create multiple feed files for different JSON structures or different data via GraphQL.
To create multiple feed files, you must add a gatsby-plugin-json-output
object and options for each feed in gatsby-config.js
.
nodesPerFeedFile
(optional)
This is an optional number (integer) of nodes to include per feed file. Defaults to 100.
Uninstall
Remove the config from your gatsby-config.js
, then:
With NPM:
npm uninstall gatsby-plugin-json-output
With Yarn:
yarn remove gatsby-plugin-json-output