rans>Skip to main content
Community Plugin
View plugin on GitHub
See starters using this

gatsby-plugin-settings

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.

Install

$ 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
[address]
streetAddress = "123 Main Street"
city = "Springfield"

Then query them as you would any other Gatsby data.

query Settings {
  siteSettings {
    contributors {
      name
      handle
    }
    social {
      facebook
      twitter
      linkedin
    }
    location {
      address {
        streetAddress
        city
      }
    }
  }
}

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:

    oops:
    - 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.
Docs
Tutorials
Plugins
Blog
Showcase