Skip to content
Gatsby plugin to manage user settings more effectively.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


npm (scoped) semantic-release styled with prettier

A Gatsby plugin to consume YAML, TOML, and/or JSON files and expose their data as global site settings via Gatsby's GraphQL layer.

NOTE: This plugin was originally developed to dovetail with NetlifyCMS's file collections feature.


$ npm install --save @raygesualdo/gatsby-plugin-settings

How to Use

Configure your Gatsby site.

// In your gatsby-config.js
plugins: [
    resolve: '@raygesualdo/gatsby-plugin-settings',
    options: {
      path: `${__dirname}/path/to/settings/directory`,

NOTE: options.path must exist before starting Gatsby!

Add and query settings files

In the directory specified in options.path, create YAML, TOML and/or JSON files.

// contributors.json
  { name: 'Jane Smith', handle: 'janesmith03' },
  { name: 'Dwayne Jones', handle: 'dwayne_jones' },
# social.yml
facebook: 'myFacebookHandle'
twitter: 'myTwitterHandle'
linkedin: 'myLinkedinHandle'
# location.toml
streetAddress = "123 Main Street"
city = "Springfield"

Then query them as you would any other Gatsby data.

query Settings {
  siteSettings {
    contributors {
    social {
    location {
      address {

The above query would result in the following data set:

  "data": {
    "siteSettings": {
      "contributors": [
          "name": "Jane Smith",
          "handle": "janesmith03"
          "name": "Dwayne Jones",
          "handle": "dwayne_jones"
      "social": {
        "facebook": "myFacebookHandle",
        "twitter": "myTwitterHandle",
        "linkedin": "myLinkedinHandle"
      "location": {
        "address": {
          "streetAddress": "123 Main Street",
          "city": "Springfield"

Things to Know

  • Currently, only one instance of this plugin is allowed per site.

  • This plugin supports the following file extensions: .yml, .yaml, .toml, and .json

  • This will add both a siteSettings and allSiteSettings fields to the root GraphQL query. Only siteSettings is to be used. allSiteSettings is a side-effect of Gatsby assuming all node types are collections.

  • When working with arrays of data, values as the same path cannot be of different types. This requirement is due to GraphQL's strongly-typed schema; neither this plugin nor Gatsby can change that. For instance, the following YAML file will throw an error:

      - 1
      - "a string"
  • This plugin watches your settings file and will hot-reload your settings when values change but your query schema does not e.g. changing a value or adding an item to a pre-existing array. Settings changes that affect your query schema will require a full restart of Gatsby's dev mode, e.g. adding a settings file or changing a key name.

You can’t perform that action at this time.