You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/configuring-usage-with-plugin-options.md
+213-7Lines changed: 213 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -54,24 +54,230 @@ The following table lists possible options values and an example plugin that mak
54
54
55
55
**Note**: Themes (which are a type of plugin) are able to receive options from a site's `gatsby-config` to be used in its `gatsby-config` in order to allow themes to be composed together. This is done by exporting the `gatsby-config` as a function instead of an object. You can see an example of this in the [`gatsby-theme-blog`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.
56
56
57
-
## How to validate options
57
+
## How to validate plugin options
58
58
59
-
In order to make configuration easier for users, plugins can optionally define a [Joi](https://joi.dev)schema to enforce data types for each option using the [`pluginOptionsSchema` API](/docs/node-apis/#pluginOptionsSchema) in `gatsby-node.js`. When users of the plugin pass in configuration options, Gatsby will validate that the options match the schema.
59
+
To help users [configure plugins](/docs/configuring-usage-with-plugin-options/) correctly, a plugin can optionally define a schema to enforce a type for each option. Gatsby will validate that the options users pass match the schema to help them correctly set up their site.
60
60
61
-
For example, here is what the schema for `gatsby-plugin-console-log` looks like:
61
+
### How to define an options schema
62
+
63
+
You should use the [`pluginOptionsSchema`](/docs/node-apis/#pluginOptionsSchema) API to define your plugins' options schema. It gets passed an instance of [Joi](https://joi.dev), which you use to return a [`Joi.object`](https://joi.dev/api/?v=17.3.0#object) schema for the options you expect users to pass.
64
+
65
+
For example, imagine you were creating a plugin called `gatsby-plugin-console-log`. You decide you want users to configure your plugin using the following options:
66
+
67
+
```javascript:title=gatsby-config.js
68
+
module.exports= {
69
+
plugins: [
70
+
{
71
+
resolve:`gatsby-plugin-console-log`,
72
+
options: {
73
+
optionA:true,
74
+
message:"Hello world"
75
+
optionB:false, // Optional.
76
+
},
77
+
},
78
+
],
79
+
}
80
+
```
81
+
82
+
You want users to pass in a boolean to `optionA` and a string to `message`, and they can optionally pass a boolean to `optionB`. To enforce these rules, you would create the following `pluginOptionsSchema`:
This ensures users pass a boolean to `optionA` and `optionB`, and a string to `message`. If they pass options that do not match the schema, the validation will show an error when they run `gatsby develop`. It also defaults the `message` option to "default message" in case users do not pass their own.
96
+
If users pass options that do not match the schema, the validation will show an error when they run `gatsby develop` and prompt them to fix their configuration.
97
+
98
+
For example, if an integer is passed into `message` (which is marked as a required string) this message would be shown:
99
+
100
+
```
101
+
ERROR #11331 PLUGIN
102
+
103
+
Invalid plugin options for "gatsby-plugin-console-log":
104
+
105
+
- "message" must be a string
106
+
```
107
+
108
+
### Best practices for option schemas
109
+
110
+
The [Joi API documentation](https://joi.dev/api/) is a great reference to use while working on a `pluginOptionsSchema`, as it shows all the available types and methods.
111
+
112
+
Here are some specific Joi best practices for `pluginOptionsSchema`:
113
+
114
+
-[Add descriptions](#add-descriptions)
115
+
-[Set default options](#set-default-options)
116
+
-[Validate external access](#validate-external-access) where necessary
117
+
-[Add custom error messages](#add-custom-error-messages) where useful
118
+
-[Deprecate options](#deprecating-options) in a major version release rather than removing them
119
+
120
+
#### Add descriptions
121
+
122
+
Make sure that every option and field has a [`.description()`](https://joi.dev/api/?v=17.3.0#anydescriptiondesc) explaining its purpose. This is helpful for documentation as users can look at the schema and understand all the options. There might also be tooling in the future that auto-generates plugin option documentation from the schema.
123
+
124
+
#### Set default options
125
+
126
+
You can use the [`.default()` method](https://joi.dev/api/?v=17.3.0#anydefaultvalue) to set a default value for an option. For example, in the `gatsby-plugin-console-log` plugin above, you could have the `message` option default to `"default message"` if a user does not pass their own `message` value:
Accessing `pluginOptions.message` would then log `"default message"` in all plugin APIs if the user does not supply their own value.
141
+
142
+
#### Validate external access
143
+
144
+
Some plugins (particularly source plugins) query external APIs. With the [`.external()`](https://joi.dev/api/?v=17.3.0#anyexternalmethod-description) method, you can asynchronously validate that the user has access to the API, providing a better experience if they pass invalid secrets.
145
+
146
+
For example, this is how the [Contentful source plugin](/plugins/gatsby-source-contentful/) might validate that the user has access to the space they are trying to query:
`Cannot access Contentful space "${pluginOptions.spaceId}" with the provided access token. Double check they are correct and try again!`
165
+
)
166
+
}
167
+
})
168
+
}
169
+
```
170
+
171
+
#### Add custom error messages
172
+
173
+
Sometimes you might want to provide more detailed error messages when validation fails for a specific field. Joi provides a [`.messages()` method](https://joi.dev/api/?v=17.3.0#anymessagesmessages) which lets you override error messages for specific [error types](https://joi.dev/api/?v=17.3.0#list-of-errors) (e.g. `"any.required"` when a `.required()` call fails).
174
+
175
+
For example, in the `gatsby-plugin-console-log` plugin above, this is how you would provide a custom error message if users do not specify `optionA`:
While you can simply remove options from the schema in major versions, that causes cryptic error messages for users upgrading with existing configuration. Instead, deprecate them using the [`.forbidden()` method](https://joi.dev/api/?v=17.3.0#anyforbidden) in a major version release. Then, [add a custom error message](#add-custom-error-messages) explaining how users should upgrade the functionality using `.messages()`.
To verify that a `pluginOptionsSchema` behaves as expected, unit test it with different configurations using the [`gatsby-plugin-utils` package](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-utils#testpluginoptionsschema).
226
+
227
+
1. Add the `gatsby-plugin-utils` package to your site:
228
+
229
+
```shell
230
+
npm install --dev gatsby-plugin-utils
231
+
```
232
+
233
+
2. Use the `testPluginOptionsSchema` function exported from the package in your test file. It takes two parameters, the plugin's actual Joi schema and an example options object to test. It returns an object with an `isValid` boolean, which will be true or false based on whether or not the options object fits the actual Joi schema, and an `errors` array, which will contain the error messages if the validation failed.
234
+
235
+
For example, with [Jest](https://jestjs.io), your tests might look something like this:
-[Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)
282
+
-[Joi API documentation](https://joi.dev/api/)
283
+
-[`pluginOptionsSchema` for the Contentful source plugin](https://github.com/gatsbyjs/gatsby/blob/af973d4647dc14c85555a2ad8f1aff08028ee3b7/packages/gatsby-source-contentful/src/gatsby-node.js#L75-L159)
0 commit comments