npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bond-london/simple-gatsby-source-graphcms

v8.12.0

Published

Bond version of the official Gatsby source plugin for GraphCMS projects

Downloads

158

Readme

This simplifies and adds some new features

  • Everything is handled in source nodes rather than later
  • Compatible with gatsby v4
  • Parallel asset downloading
  • Incremental downloading
  • Handles locales
  • Produces clean RTF
  • Locally caches assets to prevent downloading multiple times
  • Uses the new enableStatefulSourceNodes to speed up
  • Supports Gatsby cloud image CDN

Installation

yarn add @bond-london/simple-gatsby-source-graphcms

Configuration

We recommend using environment variables with your GraphCMS token and endpoint values. You can learn more about using environment variables with Gatsby here.

Basic

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
      },
    },
  ],
};

Authorization

You can also provide an auth token using the token configuration key. This is necessary if your GraphCMS project is not publicly available, or you want to scope access to a specific content stage (i.e. draft content).

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        token: process.env.GRAPHCMS_TOKEN,
      },
    },
  ],
};

Options

| Key | Type | Description | | ------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | endpoint | String (required) | The endpoint URL for the GraphCMS project. This can be found in the project settings UI. | | token | String | If your GraphCMS project is not publicly accessible, you will need to provide a Permanent Auth Token to correctly authorize with the API. You can learn more about creating and managing API tokens here. | | typePrefix | String _(Default: GraphCMS_)_ | The string by which every generated type name is prefixed with. For example, a type of Post in GraphCMS would become GraphCMS_Post by default. If using multiple instances of the source plugin, you must provide a value here to prevent type conflicts. | | downloadAllAssets | Boolean (Default: false) | Download and cache all GraphCMS assets in your Gatsby project. Learn more. | | downloadNonImageAssets | Boolean (Default: true) | Download non image assets (eg videos, svgs etc) | | cleanupRtf | Boolean (Default: true) | Create a cleaned node in RichText fields in your GraphCMS schema. These don't have empty elements and have replaced whitespace with a single space. | | buildMarkdownNodes | Boolean (Default: false) | Build markdown nodes for all RichText fields in your GraphCMS schema. Learn more. | | markdownFields | Object (Default: {}) | Which models/fields are markdown causing a markdown node to be built. Learn more. | | fragmentsPath | String (Default: graphcms-fragments) | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you must provide a value here to prevent type and/or fragment conflicts. | | locales | String (Default: ['en']) | An array of locale key strings from your GraphCMS project. Learn more. You can read more about working with localisation in GraphCMS here. This builds complete models for each locale using the fallback locale. | | stages | String (Default: ['PUBLISHED']) | An array of Content Stages from your GraphCMS project. Learn more. You can read more about using Content Stages here. | | concurrentDownloads | Number (Default: 50) | How many asset downloads to run in parallel. | | dontDownload | Boolean (Default: false) | Set to true to don't download any assets in case of slow bandwidth | | localCache | Boolean (Default: false) | Set to true to cache assets locally outside the standard gatsby cache folders | | localCacheDir | String (Default: .bondgraphcmsassets) | Set to the name of the local cache directory |

Features

Querying localised nodes

If using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.

Update your plugin configuration to include the locales key.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        locales: ["en", "de"],
      },
    },
  ],
};

To query for nodes for a specific locale, use the filter query argument.

{
  enProducts: allGraphCmsProduct(filter: { locale: { eq: en } }) {
    nodes {
      name
    }
  }
}

This creates local content nodes for all the locales produced. This allows simple multiple locale sites to be produced from partially localised content in the CMS.

Querying from content stages

This plugin provides support to build nodes for entries from multiple Content Stages.

The provided Content Stages must be accessible according to the configuration of your project's API access. If providing a token, then that Permanent Auth Token must have permission to query data from all provided Content Stages.

The example below assumes that both the DRAFT and PUBLISHED stages are publicly accessible.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        stages: ["DRAFT", "PUBLISHED"],
      },
    },
  ],
};

To query for nodes from a specific Content Stage, use the filter query argument.

{
  allGraphCmsProduct(filter: { stage: { eq: DRAFT } }) {
    nodes {
      name
    }
  }
}

Usage with gatsby-plugin-image

Requires gatsby-plugin-image as a project dependency.

This source plugin supports gatsby-plugin-image for responsive, high performance GraphCMS images direct from our CDN.

Use the gatsbyImageData resolver on your GraphCMS_Asset nodes.

{
  allGraphCmsAsset {
    nodes {
      gatsbyImageData(layout: FULL_WIDTH)
    }
  }
}

gatsbyImageData resolver arguments

| Key | Type | Description | | ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | aspectRatio | Float | Force a specific ratio between the image’s width and height. | | backgroundColor | String | Background color applied to the wrapper. | | breakpoints | [Int] | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. | | height | Int | Change the size of the image. | | layout | GatsbyImageLayout (CONSTRAINED/FIXED/FULL_WIDTH) | Determines the size of the image and its resizing behavior. | | outputPixelDensities | [Float] | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a 400 px wide constrained image would generate 100, 200, 400 and 800 px wide images by default. Ignored for full width layout images, which use breakpoints instead. | | quality | Int | The default image quality generated. This is overridden by any format-specific options. | | sizes | String | The <img> sizes attribute, passed to the img tag. This describes the display size of the image, and does not affect generated images. You are only likely to need to change this if your are using full width images that do not span the full width of the screen. | | width | Int | Change the size of the image. |

For more information on using gatsby-plugin-image, please see the documentation.

Downloading local image assets

If you prefer, the source plugin also provides the option to download and cache GraphCMS assets in your Gatsby project.

To enable this, add downloadAllAssets: true to your plugin configuration. This downloads all assets.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        downloadAllAssets: true,
      },
    },
  ],
};

This adds a localFile field to the GraphCMS_Asset type which resolves to the file node generated at build by gatsby-source-filesystem.

{
  allGraphCmsAsset {
    nodes {
      localFile {
        childImageSharp {
          gatsbyImageData(layout: FULL_WIDTH)
        }
      }
    }
  }
}

Using markdown nodes

This source plugin provides the option to build markdown nodes for all RichText fields in your GraphCMS schema, which in turn can be used with MDX.

To enable this, add buildMarkdownNodes: true to your plugin configuration.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        buildMarkdownNodes: true,
      },
    },
  ],
};

Enabling this option adds a markdownNode nested field to all RichText fields on the generated Gatsby schema.

Usage with gatsby-plugin-mdx

These newly built nodes can be used with gatsby-plugin-mdx to render markdown from GraphCMS.

Once installed, you will be able to query for MDX fields using a query similar to the one below.

{
  allGraphCmsPost {
    nodes {
      id
      content {
        markdownNode {
          childMdx {
            body
          }
        }
      }
    }
  }
}

Check out the demo source for an example of a full MDX implementation.

Using markdown fields

This source plugin provides the option to build markdown nodes for all RichText fields in your GraphCMS schema, which in turn can be used with MDX.

To enable this, add something like markdownFields: {Author: ['description']} to your plugin configuration.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        markdownFields: { Author: ["description"] },
      },
    },
  ],
};

Enabling this option adds a descriptionMarkdownNode field to the description fields on the Author schema. Other fields and schemas are added the same way

Working with query fragments

The source plugin will generate and save GraphQL query fragments for every node type. By default, they will be saved in a graphcms-fragments directory at the root of your Gatsby project. This can be configured:

If using multiple instances of the source plugin, you must provide a value to prevent type and/or fragment conflicts.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@bond-london/simple-gatsby-source-graphcms",
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        fragmentsPath: "my-query-fragments",
      },
    },
  ],
};

The generated fragments are then read from the project for subsequent builds. It is recommended that they are checked in to version control for your project.

Should you make any changes or additions to your GraphCMS schema, you will need to update the query fragments accrdingly. Alternatively they will be regnerated on a subsequent build after removing the directory from your project.

Modifying query fragments

In some instances, you may need modify query fragments on a per type basis. This may involve:

  • Removing unrequired fields
  • Adding new fields with arguments as an aliased field

For example, adding a featuredCaseStudy field:

fragment Industry on Industry {
  featuredCaseStudy: caseStudies(where: { featured: true }, first: 1)
}

Field arguments cannot be read by Gatsby from the GraphCMS schema. Instead we must alias any required usages as aliased fields. In this example, the featuredCaseStudy field would then be available in our Gatsby queries:

{
  allGraphCmsIndustry {
    nodes {
      featuredCaseStudy {
        ...
      }
    }
  }
}