Neurophysiologically Pseudoscientific Manatee

    gatsby-plugin-json-output
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    Gatsby Plugin - JSON Output

    Fetch JSON content from Gatsby with API-like static feeds that automatically update with your builds.

    1. Can create individual JSON view of each generated static HTML file. For example: /about/index.html would also have a /about/index.json
    2. 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.js
    const 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
                    }
                  }
                }
              }
            }
          `,
          serialize: results => results.data.allMarkdownRemark.edges.map(({ node }) => ({
            path: node.fields.path, // MUST contain a path
            title: node.frontmatter.title,
            created: node.frontmatter.created,
            updated: node.frontmatter.updated,
            html: node.html,
          })),
          feedMeta: {
            author: {
              name: author,
            },
            description: siteDescription,
            favicon: `${siteUrl}/icons/icon-48x48.png`,
            title: siteTitle,
          },
          serializeFeed: results => results.data.allMarkdownRemark.edges.map(({ node }) => ({
            id: node.fields.path,
            url: siteUrl + node.fields.path,
            title: node.frontmatter.title,
            date_published: new Date(node.frontmatter.created).toISOString(),
            date_modified: new Date(node.frontmatter.updated).toISOString(),
            excerpt: node.excerpt,
          })),
          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:

    {
      allMarkdownRemark(limit: 1000) {
        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
    serialize: results =>
      results.data.allMarkdownRemark.edges.map(({ node }) => ({
        path: node.fields.path, // MUST contain a path
        title: node.frontmatter.title,
        created: node.frontmatter.created,
        updated: node.frontmatter.updated,
        html: node.html
      }));
     
    // Or traditional functions
    serialize: function serialize(results) {
      var nodes = [];
     
      for (var i = 0; i < results.data.allMarkdownRemark.edges.length; i++) {
        var node = results.data.allMarkdownRemark.edges[i].node;
     
        nodes.push({
          path: node.fields.path, // MUST contain a path
          title: node.frontmatter.title,
          created: node.frontmatter.created,
          updated: node.frontmatter.updated,
          html: node.html
        });
     
        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
    serializeFeed: results => results.data.allMarkdownRemark.edges.map(({ node }) => ({
      id: nodes.field.path
      url: path.join(siteUrl, node.fields.path),
      title: node.frontmatter.title,
      date_published: new Date(node.frontmatter.created).toISOString(),
      date_modified: new Date(node.frontmatter.updated).toISOString(),
      excerpt: node.excerpt,
    }))

    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:

    {
      "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",
      "feed_url": "https://example.com/feed-1.json",
      "home_page_url": "https://example.com",
      "items": [
        {
          "date_modified": "2019-03-02T00:00:00.000Z",
          "date_published": "2019-03-02T00:00:00.000Z",
          "excerpt": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc at ultricies metus, vel hendrerit magna. Nullam iaculis faucibus feugiat. Mauris mollis, est eu congue placerat, ex odio auctor odio, sed viverra mi nulla in orci.",
          "id": "/lorem-ipsum-dolor-sit-amet",
          "title": "Lorem ipsum dolor sit amet",
          "url": "https://example.com/lorem-ipsum-dolor-sit-amet",
        }
      ],
      "next_feed_url": "https://example.com/feed-2.json",
      "previous_feed_url": null,
      "version": "https://jsonfeed.org/version/1"
    }

    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

    Install

    npm i gatsby-plugin-json-output

    DownloadsWeekly Downloads

    8,702

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    41.8 kB

    Total Files

    33

    Last publish

    Collaborators

    • dominicfallows