The official Gatsby source plugin for GraphCMS projects • Demo • gatsby-starter-graphcms-blog
\n\nThis is copied from the main repository to test a few fixes and tweaks.\n\n## Installation\n\n```shell\nyarn add gatsby-source-graphcms gatsby-plugin-image\n```\n\n## Configuration\n\n> We recommend using environment variables with your GraphCMS `token` and `endpoint` values. You can learn more about using environment variables with Gatsby [here](https://www.gatsbyjs.org/docs/environment-variables).\n\n### Basic\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n },\n },\n ],\n};\n```\n\n### Authorization\n\nYou can also provide an auth token using the `token` configuration key. This is necessary if your GraphCMS project is **not** publicly available, or you want to scope access to a specific content stage (i.e. draft content).\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n token: process.env.GRAPHCMS_TOKEN,\n },\n },\n ],\n};\n```\n\n### Options\n\n| Key | Type | Description |\n| --------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `endpoint` | String (**required**) | The endpoint URL for the GraphCMS project. This can be found in the [project settings UI](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `token` | String | If your GraphCMS project is **not** publicly accessible, you will need to provide a [Permanent Auth Token](https://graphcms.com/docs/reference/authorization) to correctly authorize with the API. You can learn more about creating and managing API tokens [here](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `typePrefix` | String _(Default: `GraphCMS_`)\\_ | The string by which every generated type name is prefixed with. For example, a type of `Post` in GraphCMS would become `GraphCMS_Post` by default. If using multiple instances of the source plugin, you **must** provide a value here to prevent type conflicts. |\n| `downloadLocalImages` | Boolean _(Default: `false`)_ | Download and cache GraphCMS image assets in your Gatsby project. [Learn more](#downloading-local-image-assets). |\n| `downloadAllAssets` | Boolean _(Default: `false`)_ | Download and cache all GraphCMS assets in your Gatsby project. [Learn more](#downloading-local-image-assets). |\n| `buildMarkdownNodes` | Boolean _(Default: `false`)_ | Build markdown nodes for all [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. [Learn more](#using-markdown-nodes). |\n| `fragmentsPath` | String _(Default: `graphcms-fragments`)_ | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you **must** provide a value here to prevent type and/or fragment conflicts. |\n| `locales` | String _(Default: `['en']`)_ | An array of locale key strings from your GraphCMS project. [Learn more](#querying-localised-nodes). You can read more about working with localisation in GraphCMS [here](https://graphcms.com/docs/guides/concepts/i18n). |\n| `stages` | String _(Default: `['PUBLISHED']`)_ | An array of Content Stages from your GraphCMS project. [Learn more](#querying-from-content-stages). You can read more about using Content Stages [here](https://graphcms.com/guides/working-with-content-stages). |\n\n## Features\n\n- [Querying localised nodes](#querying-localised-nodes)\n- [Querying from content stages](#querying-from-content-stages)\n- [Usage with `gatsby-plugin-image`](#usage-with-gatsby-plugin-image)\n- [Downloading local image assets](#downloading-local-image-assets)\n- [Using markdown nodes](#using-markdown-nodes)\n- [Working with query fragments](#working-with-query-fragments)\n\n### Querying localised nodes\n\nIf using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.\n\nUpdate your plugin configuration to include the `locales` key.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n locales: [\"en\", \"de\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes for a specific locale, use the `filter` query argument.\n\n```gql\n{\n enProducts: allGraphCmsProduct(filter: { locale: { eq: en } }) {\n nodes {\n name\n }\n }\n}\n```\n\nCheck out the [demo source](https://github.com/GraphCMS/gatsby-source-graphcms/tree/main/demo) for an example of a localisation implementation.\n\n### Querying from content stages\n\nThis plugin provides support to build nodes for entries from multiple Content Stages.\n\nThe provided Content Stages **must** be accessible according to the configuration of your project's [API access](https://graphcms.com/docs/authorization). If providing a `token`, then that [Permanent Auth Token](https://graphcms.com/docs/authorization#permanent-auth-tokens) must have permission to query data from all provided Content Stages.\n\nThe example below assumes that both the `DRAFT` and `PUBLISHED` stages are publicly accessible.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n stages: [\"DRAFT\", \"PUBLISHED\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes from a specific Content Stage, use the `filter` query argument.\n\n```gql\n{\n allGraphCmsProduct(filter: { stage: { eq: DRAFT } }) {\n nodes {\n name\n }\n }\n}\n```\n\n### Usage with `gatsby-plugin-image`\n\n> Requires [`gatsby-plugin-image`](https://www.gatsbyjs.com/plugins/gatsby-plugin-image) as a project dependency.\n\nThis source plugin supports `gatsby-plugin-image` for responsive, high performance GraphCMS images direct from our CDN.\n\nUse the `gatsbyImageData` resolver on your `GraphCMS_Asset` nodes.\n\n```gql\n{\n allGraphCmsAsset {\n nodes {\n gatsbyImageData(layout: FULL_WIDTH)\n }\n }\n}\n```\n\n#### `gatsbyImageData` resolver arguments\n\n| Key | Type | Description |\n| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `aspectRatio` | Float | Force a specific ratio between the image’s width and height. |\n| `backgroundColor` | String | Background color applied to the wrapper. |\n| `breakpoints` | [Int] | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. |\n| `height` | Int | Change the size of the image. |\n| `layout` | GatsbyImageLayout (`CONSTRAINED`/`FIXED`/`FULL_WIDTH`) | Determines the size of the image and its resizing behavior. |\n| `outputPixelDensities` | [Float] | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a `400` px wide constrained image would generate `100`, `200`, `400` and `800` px wide images by default. Ignored for full width layout images, which use `breakpoints` instead. |\n| `quality` | Int | The default image quality generated. This is overridden by any format-specific options. |\n| `sizes` | String | [The `A port/rebuild of the official gatsby graphcms source plugin
\n\nThis simplifies and adds some new features\n\n- Everything is handled in source nodes rather than later\n- Compatible with gatsby v4\n- Parallel asset downloading\n- Incremental downloading\n- Handles locales\n\n## Installation\n\n```shell\nyarn add @bond-london/simple-gatsby-source-graphcms\n```\n\n## Configuration\n\n> We recommend using environment variables with your GraphCMS `token` and `endpoint` values. You can learn more about using environment variables with Gatsby [here](https://www.gatsbyjs.org/docs/environment-variables).\n\n### Basic\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n },\n },\n ],\n};\n```\n\n### Authorization\n\nYou can also provide an auth token using the `token` configuration key. This is necessary if your GraphCMS project is **not** publicly available, or you want to scope access to a specific content stage (i.e. draft content).\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n token: process.env.GRAPHCMS_TOKEN,\n },\n },\n ],\n};\n```\n\n### Options\n\n| Key | Type | Description |\n| --------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `endpoint` | String (**required**) | The endpoint URL for the GraphCMS project. This can be found in the [project settings UI](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `token` | String | If your GraphCMS project is **not** publicly accessible, you will need to provide a [Permanent Auth Token](https://graphcms.com/docs/reference/authorization) to correctly authorize with the API. You can learn more about creating and managing API tokens [here](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `typePrefix` | String _(Default: `GraphCMS_`)\\_ | The string by which every generated type name is prefixed with. For example, a type of `Post` in GraphCMS would become `GraphCMS_Post` by default. If using multiple instances of the source plugin, you **must** provide a value here to prevent type conflicts. |\n| `downloadAllAssets` | Boolean _(Default: `false`)_ | Download and cache all GraphCMS assets in your Gatsby project. [Learn more](#downloading-local-image-assets). |\n| `buildMarkdownNodes` | Boolean _(Default: `false`)_ | Build markdown nodes for all [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. [Learn more](#using-markdown-nodes). |\n| `markdownFields` | Object _(Default: `{}`)_ | Which models/fields are markdown causing a markdown node to be built. [Learn more](#using-markdown-fields). |\n| `fragmentsPath` | String _(Default: `graphcms-fragments`)_ | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you **must** provide a value here to prevent type and/or fragment conflicts. |\n| `locales` | String _(Default: `['en']`)_ | An array of locale key strings from your GraphCMS project. [Learn more](#querying-localised-nodes). You can read more about working with localisation in GraphCMS [here](https://graphcms.com/docs/guides/concepts/i18n). This builds complete models for each locale using the fallback locale. |\n| `stages` | String _(Default: `['PUBLISHED']`)_ | An array of Content Stages from your GraphCMS project. [Learn more](#querying-from-content-stages). You can read more about using Content Stages [here](https://graphcms.com/guides/working-with-content-stages). |\n| `concurrency` | Number _(Default: `10`)_ | How many content downloads to run concurrently. |\n| `concurrentDownloads` | Number _(Default: `10`)_ | How many asset downloads to run in parallel. |\n\n## Features\n\n- [Querying localised nodes](#querying-localised-nodes)\n- [Querying from content stages](#querying-from-content-stages)\n- [Usage with `gatsby-plugin-image`](#usage-with-gatsby-plugin-image)\n- [Downloading local image assets](#downloading-local-image-assets)\n- [Using markdown nodes](#using-markdown-nodes)\n- [Using markdown nodes](#using-markdown-fields)\n- [Working with query fragments](#working-with-query-fragments)\n\n### Querying localised nodes\n\nIf using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.\n\nUpdate your plugin configuration to include the `locales` key.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n locales: [\"en\", \"de\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes for a specific locale, use the `filter` query argument.\n\n```gql\n{\n enProducts: allGraphCmsProduct(filter: { locale: { eq: en } }) {\n nodes {\n name\n }\n }\n}\n```\n\nThis creates local content nodes for all the locales produced. This allows simple multiple locale sites to be produced from partially localised content in the CMS.\n\n### Querying from content stages\n\nThis plugin provides support to build nodes for entries from multiple Content Stages.\n\nThe provided Content Stages **must** be accessible according to the configuration of your project's [API access](https://graphcms.com/docs/authorization). If providing a `token`, then that [Permanent Auth Token](https://graphcms.com/docs/authorization#permanent-auth-tokens) must have permission to query data from all provided Content Stages.\n\nThe example below assumes that both the `DRAFT` and `PUBLISHED` stages are publicly accessible.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n stages: [\"DRAFT\", \"PUBLISHED\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes from a specific Content Stage, use the `filter` query argument.\n\n```gql\n{\n allGraphCmsProduct(filter: { stage: { eq: DRAFT } }) {\n nodes {\n name\n }\n }\n}\n```\n\n### Usage with `gatsby-plugin-image`\n\n> Requires [`gatsby-plugin-image`](https://www.gatsbyjs.com/plugins/gatsby-plugin-image) as a project dependency.\n\nThis source plugin supports `gatsby-plugin-image` for responsive, high performance GraphCMS images direct from our CDN.\n\nUse the `gatsbyImageData` resolver on your `GraphCMS_Asset` nodes.\n\n```gql\n{\n allGraphCmsAsset {\n nodes {\n gatsbyImageData(layout: FULL_WIDTH)\n }\n }\n}\n```\n\n#### `gatsbyImageData` resolver arguments\n\n| Key | Type | Description |\n| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `aspectRatio` | Float | Force a specific ratio between the image’s width and height. |\n| `backgroundColor` | String | Background color applied to the wrapper. |\n| `breakpoints` | [Int] | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. |\n| `height` | Int | Change the size of the image. |\n| `layout` | GatsbyImageLayout (`CONSTRAINED`/`FIXED`/`FULL_WIDTH`) | Determines the size of the image and its resizing behavior. |\n| `outputPixelDensities` | [Float] | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a `400` px wide constrained image would generate `100`, `200`, `400` and `800` px wide images by default. Ignored for full width layout images, which use `breakpoints` instead. |\n| `quality` | Int | The default image quality generated. This is overridden by any format-specific options. |\n| `sizes` | String | [The `A port/rebuild of the official gatsby graphcms source plugin
\n\nThis simplifies and adds some new features\n\n- Everything is handled in source nodes rather than later\n- Compatible with gatsby v4\n- Parallel asset downloading\n- Incremental downloading\n- Handles locales\n- Produces clean RTF\n- Locally caches assets to prevent downloading multiple times\n- Uses the new enableStatefulSourceNodes to speed up\n- Supports Gatsby cloud image CDN\n\n## Installation\n\n```shell\nyarn add @bond-london/simple-gatsby-source-graphcms\n```\n\n## Configuration\n\n> We recommend using environment variables with your GraphCMS `token` and `endpoint` values. You can learn more about using environment variables with Gatsby [here](https://www.gatsbyjs.org/docs/environment-variables).\n\n### Basic\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"@bond-london/simple-gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n },\n },\n ],\n};\n```\n\n### Authorization\n\nYou can also provide an auth token using the `token` configuration key. This is necessary if your GraphCMS project is **not** publicly available, or you want to scope access to a specific content stage (i.e. draft content).\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"@bond-london/simple-gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n token: process.env.GRAPHCMS_TOKEN,\n },\n },\n ],\n};\n```\n\n### Options\n\n| Key | Type | Description |\n| ------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `endpoint` | String (**required**) | The endpoint URL for the GraphCMS project. This can be found in the [project settings UI](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `token` | String | If your GraphCMS project is **not** publicly accessible, you will need to provide a [Permanent Auth Token](https://graphcms.com/docs/reference/authorization) to correctly authorize with the API. You can learn more about creating and managing API tokens [here](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |\n| `typePrefix` | String _(Default: `GraphCMS_`)\\_ | The string by which every generated type name is prefixed with. For example, a type of `Post` in GraphCMS would become `GraphCMS_Post` by default. If using multiple instances of the source plugin, you **must** provide a value here to prevent type conflicts. |\n| `downloadAllAssets` | Boolean _(Default: `false`)_ | Download and cache all GraphCMS assets in your Gatsby project. [Learn more](#downloading-local-image-assets). |\n| `downloadNonImageAssets` | Boolean _(Default: `true`)_ | Download non image assets (eg videos, svgs etc) |\n| `cleanupRtf` | Boolean _(Default: `true`)_ | Create a cleaned node in [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. These don't have empty elements and have replaced whitespace with a single space. |\n| `buildMarkdownNodes` | Boolean _(Default: `false`)_ | Build markdown nodes for all [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. [Learn more](#using-markdown-nodes). |\n| `markdownFields` | Object _(Default: `{}`)_ | Which models/fields are markdown causing a markdown node to be built. [Learn more](#using-markdown-fields). |\n| `fragmentsPath` | String _(Default: `graphcms-fragments`)_ | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you **must** provide a value here to prevent type and/or fragment conflicts. |\n| `locales` | String _(Default: `['en']`)_ | An array of locale key strings from your GraphCMS project. [Learn more](#querying-localised-nodes). You can read more about working with localisation in GraphCMS [here](https://graphcms.com/docs/guides/concepts/i18n). This builds complete models for each locale using the fallback locale. |\n| `stages` | String _(Default: `['PUBLISHED']`)_ | An array of Content Stages from your GraphCMS project. [Learn more](#querying-from-content-stages). You can read more about using Content Stages [here](https://graphcms.com/guides/working-with-content-stages). |\n| `concurrentDownloads` | Number _(Default: `50`)_ | How many asset downloads to run in parallel. |\n| `dontDownload` | Boolean _(Default: `false`)_ | Set to true to don't download any assets in case of slow bandwidth |\n| `localCache` | Boolean _(Default: `false`)_ | Set to true to cache assets locally outside the standard gatsby cache folders |\n| `localCacheDir` | String _(Default: `.bondgraphcmsassets`)_ | Set to the name of the local cache directory |\n\n## Features\n\n- [Querying localised nodes](#querying-localised-nodes)\n- [Querying from content stages](#querying-from-content-stages)\n- [Usage with `gatsby-plugin-image`](#usage-with-gatsby-plugin-image)\n- [Downloading local image assets](#downloading-local-image-assets)\n- [Using markdown nodes](#using-markdown-nodes)\n- [Using markdown nodes](#using-markdown-fields)\n- [Working with query fragments](#working-with-query-fragments)\n\n### Querying localised nodes\n\nIf using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.\n\nUpdate your plugin configuration to include the `locales` key.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"@bond-london/simple-gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n locales: [\"en\", \"de\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes for a specific locale, use the `filter` query argument.\n\n```gql\n{\n enProducts: allGraphCmsProduct(filter: { locale: { eq: en } }) {\n nodes {\n name\n }\n }\n}\n```\n\nThis creates local content nodes for all the locales produced. This allows simple multiple locale sites to be produced from partially localised content in the CMS.\n\n### Querying from content stages\n\nThis plugin provides support to build nodes for entries from multiple Content Stages.\n\nThe provided Content Stages **must** be accessible according to the configuration of your project's [API access](https://graphcms.com/docs/authorization). If providing a `token`, then that [Permanent Auth Token](https://graphcms.com/docs/authorization#permanent-auth-tokens) must have permission to query data from all provided Content Stages.\n\nThe example below assumes that both the `DRAFT` and `PUBLISHED` stages are publicly accessible.\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: \"@bond-london/simple-gatsby-source-graphcms\",\n options: {\n endpoint: process.env.GRAPHCMS_ENDPOINT,\n stages: [\"DRAFT\", \"PUBLISHED\"],\n },\n },\n ],\n};\n```\n\nTo query for nodes from a specific Content Stage, use the `filter` query argument.\n\n```gql\n{\n allGraphCmsProduct(filter: { stage: { eq: DRAFT } }) {\n nodes {\n name\n }\n }\n}\n```\n\n### Usage with `gatsby-plugin-image`\n\n> Requires [`gatsby-plugin-image`](https://www.gatsbyjs.com/plugins/gatsby-plugin-image) as a project dependency.\n\nThis source plugin supports `gatsby-plugin-image` for responsive, high performance GraphCMS images direct from our CDN.\n\nUse the `gatsbyImageData` resolver on your `GraphCMS_Asset` nodes.\n\n```gql\n{\n allGraphCmsAsset {\n nodes {\n gatsbyImageData(layout: FULL_WIDTH)\n }\n }\n}\n```\n\n#### `gatsbyImageData` resolver arguments\n\n| Key | Type | Description |\n| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `aspectRatio` | Float | Force a specific ratio between the image’s width and height. |\n| `backgroundColor` | String | Background color applied to the wrapper. |\n| `breakpoints` | [Int] | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. |\n| `height` | Int | Change the size of the image. |\n| `layout` | GatsbyImageLayout (`CONSTRAINED`/`FIXED`/`FULL_WIDTH`) | Determines the size of the image and its resizing behavior. |\n| `outputPixelDensities` | [Float] | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a `400` px wide constrained image would generate `100`, `200`, `400` and `800` px wide images by default. Ignored for full width layout images, which use `breakpoints` instead. |\n| `quality` | Int | The default image quality generated. This is overridden by any format-specific options. |\n| `sizes` | String | [The `