# gatsby-plugin-utils > Gatsby utils that help creating plugins Latest version **4.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads ## Install ```sh npm install gatsby-plugin-utils pnpm add gatsby-plugin-utils yarn add gatsby-plugin-utils bun add gatsby-plugin-utils ``` ## Health **Score 65/100 (B)** — status: stable. Positive: esm support; no vulnerabilities; high maintenance score; popular repo; extremely popular. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 4.16.0 | | Published | 2026-01-26 | | First published | 2020-10-06 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=18.0.0 <26 | | Dependencies | 9 | | Unpacked size | 194.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 55939 | | Author | Max Stoiber | | Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, wardpeet | | Keywords | gatsby | ## Links - npm: https://www.npmjs.com/package/gatsby-plugin-utils - Repository: https://github.com/gatsbyjs/gatsby - Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-utils#readme - Issues: https://github.com/gatsbyjs/gatsby/issues - npm.io page: https://npm.io/package/gatsby-plugin-utils ## Dependencies (9) - [joi](https://npm.io/package/joi.md) ^17.11.0 - [mime](https://npm.io/package/mime.md) ^3.0.0 - [fastq](https://npm.io/package/fastq.md) ^1.16.0 - [fs-extra](https://npm.io/package/fs-extra.md) ^11.2.0 - [import-from](https://npm.io/package/import-from.md) ^4.0.0 - [gatsby-sharp](https://npm.io/package/gatsby-sharp.md) ^1.16.0 - [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13 - [graphql-compose](https://npm.io/package/graphql-compose.md) ^9.0.10 - [gatsby-core-utils](https://npm.io/package/gatsby-core-utils.md) ^4.16.0 ## Recent versions - 4.16.0 (latest) — 2026-01-26 - 4.17.0-next.0 (next) — 2025-11-27 - 4.17.0-react19.1 (react19) — 2025-11-26 - 4.13.0-alpha-alt-image-cdn.44 (alt-image-cdn) — 2023-11-03 - 4.9.0-image-cdn-configurable.4 (image-cdn-configurable) — 2023-04-11 - 1.15.0 (latest-v3) — 2022-12-07 - 3.19.0 (latest-v4) — 2022-12-07 - 4.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22 - 3.18.1-alpha-wordpress-image-err.27 (wordpress-image-err) — 2022-11-09 - 3.8.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12 - 4.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12 - 3.19.0-alpha-image-cdn-pathprefix.48 (image-cdn-pathprefix) — 2022-10-07 - 3.17.0-alpha-image-cdn-enc.40 (image-cdn-enc) — 2022-09-16 - 3.17.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14 - 3.17.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08 - … 306 more at https://npm.io/package/gatsby-plugin-utils/versions ## README # gatsby-plugin-utils ## Usage ```shell npm install gatsby-plugin-utils ``` ### `validateOptionsSchema` The `validateOptionsSchema` function verifies that the proper data types of options were passed into a plugin from the `gatsby-config.js` file. It is called internally by Gatsby to validate each plugin's options when a site is started. #### Example ```js import { validateOptionsSchema } from "gatsby-plugin-utils" await validateOptionsSchema(pluginName, pluginSchema, pluginOptions) ``` ### `testPluginOptionsSchema` Utility to validate and test plugin options schemas. An example of a plugin options schema implementation can be found in the [`gatsby-node.js` file of `gatsby-plugin-google-analytics`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-google-analytics/src/gatsby-node.js). #### Example ```js // This is an example using Jest (https://jestjs.io/) import { testPluginOptionsSchema } from "gatsby-plugin-utils" it(`should partially validate one value of a schema`, async () => { const pluginSchema = ({ Joi }) => Joi.object({ someOtherValue: Joi.string(), toVerify: Joi.boolean(), }) const expectedErrors = [`"toVerify" must be a boolean`] // Only the "toVerify" key of the schema will be verified in this test const { isValid, errors } = await testPluginOptionsSchema(pluginSchema, { toVerify: `abcd`, }) expect(isValid).toBe(false) expect(errors).toEqual(expectedErrors) }) ``` ### `isGatsbyNodeLifecycleSupported` Utility to be used by plugins to do runtime check against `gatsby` core package checking wether particular `gatsby-node` lifecycle API is supported. Useful for plugins to be able to support multiple `gatsby` core versions. #### Example ```js const { isGatsbyNodeLifecycleSupported } = require(`gatsby-plugin-utils`) // only use createSchemaCustomization lifecycle only when it's available. if (isGatsbyNodeLifecycleSupported(`createSchemaCustomization`)) { exports.createSchemaCustomization = function createSchemaCustomization({ actions, }) { // customize schema } } ``` ### `hasFeature` Feature detection is now part of Gatsby. As a plugin author you don't know what version of Gatsby a user is using. `hasFeature` allows you to check if the current version of Gatsby has a certain feature. Here's a list of features: // TODO #### Example ```js const { hasFeature } = require(`gatsby-plugin-utils`) if (!hasFeature(`image-cdn`)) { // You can polyfill image-cdn here so older versions have support as well } ``` ### Add ImageCDN support Our new ImageCDN allows source plugins to lazily download and process images. if you're a plugin author please use this polyfill to add support for all Gatsby V4 versions. For more information (see here)[https://gatsby.dev/img] #### Example ```js const { addRemoteFilePolyfillInterface, polyfillImageServiceDevRoutes, } = require(`gatsby-plugin-utils/pollyfill-remote-file`) exports.createSchemaCustomization ({ actions, schema, store }) => { actions.createTypes([ addRemoteFilePolyfillInterface( schema.buildObjectType({ name: `PrefixAsset`, fields: { // your fields }, interfaces: [`Node`, 'RemoteFile'], }), { schema, actions, store } ) ]); } /** @type {import('gatsby').onCreateDevServer} */ exports.onCreateDevServer = ({ app, store }) => { polyfillImageServiceDevRoutes(app, store) } ``` --- _Source: https://npm.io/package/gatsby-plugin-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._