@raygesualdo/gatsby-plugin-settings
v1.0.2
Published
Gatsby plugin to manage user settings more effectively
Downloads
5
Readme
gatsby-plugin-settings
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
andallSiteSettings
fields to the root GraphQL query. OnlysiteSettings
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.