Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


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.

© 2023 Gatsby, Inc.