gatsby-plugin-source-graphql-files

gatsby-plugin-source-graphql-files

Let's say you are using a headless cms like strapi as content source and for your final gatsby site you want all media that points to that cms to be included statically. This is what this plugin is intended for. Furthermore it allows you to use images with gatsby-image.

This plugin is a work in progress and could potentially contain a lot of bugs. Contributions are very welcome.

What about images embeded in e.g. markdown?

You can specify the transformFields option to add additional fields where the remote links are replaced with the static url's.

How to use

// In your gatsby-config.js
module.exports = {
  plugins: [
    resolve: `gatsby-plugin-source-graphql-files`,
    options: {
      sources: {
        endpoint: 'https://example.com/graphql',
        query: `
          {
            files {
              id
              url
            }
          }
        `,
        source: ({ files }) => files,
      },
      files: {
        typeName: 'CMS_UploadFile',
      },
      transformFields: [
        {
          baseUrl: 'https://example.com',
          typeName: 'CMS_ComponentContentParagraph',
          fieldName: 'Content',
        },
      ],
    },
  ]
}

Note: In order to resolve the correct file node you must include the id in your queries like so:

{
  cms {
    files {
      id # <- Don't forget
      staticFile {
        publicURL
      }
    }
  }
}

Options

sources: SourceOptions | Array<SourceOptions>

interface SourceOptions {
  endpoint: string // Graphql endpoint
  query: string // Query to fetch url's and id's
  // A function to map the query result to an array of url's and id's
  source: (queryResult: Object) => Array<{ url: string; id: string }>
  options?: Object // @see graphql-request
  variables?: Object
}

files: FileOptions | Array<FileOptions>

interface FileOptions {
  typeName: string // Graphql type that will get the static field added
  staticFieldName?: string // @default 'staticFile'
}

transformFields: TransformFieldOptions | Array<TransformFieldOptions>

interface TransformFieldOptions {
  baseUrl: string // Url that will be used in the regex to find remote file url's
  typeName: string // Graphql type to add transformation field
  fieldName: string // The field that contains the content to transform
  transformFieldName?: string // @default <fieldName>Transformed
  /*
   * Functiont that produces a regular expression to match remote url's
   * @default ({ baseUrl }) => new RegExp(`${_.escapeRegExp(baseUrl)}[^ )]+`, 'g')
   */
  regex?: (options: TransformFieldOptions) => RegExp
}

How does it work

This plugin sources files by querying graphql endpoints for files and then utilizing gatsby-source-filesystem to download them. Afterwards the graphql types specified under the files option get an additional field that points to the downloaded file node.

For the transformation of fields a regular expression is used to identify remote file paths and replace them with their static counterpart.