gatsby-source-s3-asset

What is this?

gatsby-source-s3-asset is a GatsbyJS Source plugin to obtain objects from any S3-compliant API[1] as GatsbyJS nodes.

[1] This includes AWS S3, of course, as well as third-party solutions like Digital Ocean Spaces, or open source / self-hosted products like MinIO.

This plugin is based on gatsby-source-s3-image. The major difference is that this version does not download any files nor analyzes their contents in any way. The goal is just to list assets and provide their publicly-accessible URLs to gastby's internal GraphQL.

But I can just query S3 manually client-side...

Sure, knock yourself out. But there are a few benefits you get out-of-the-box with this package:

Native integration with Gatsby's GraphQL data ontology, of course. You just provide the bucket details (and IAM credentials, if not public, which is recommended).

Usage

Setup

Add the dependency to your package.json:

$ yarn add gatsby-source-s3-asset
$ # Or:
$ npm install --save gatsby-source-s3-asset

Next, register the plugin with the GatsbyJS runtime in the plugins field exported from your gatsby-config.js file, filling in the values to point to wherever your bucket is hosted:

const sourceS3 = {
  resolve: 'gatsby-source-s3-asset',
  options: {
    bucketName: 'jesse.pics',
    domain: null, // [optional] Not necessary to define for AWS S3; defaults to `s3.amazonaws.com`
    protocol: 'https', // [optional] Default to `https`.
    publicDomain: null, // [optional] Use this domain to construct the public URL for the assets
  },
}

const plugins = [
  sourceS3,
  // ...
]

module.exports = { plugins }

Querying

As mentioned above, gatsby-source-s3-asset exposes nodes of type S3Asset:

interface S3AssetNode {
  id: string
  LastModified: Date
  ETag: string
  Key: string
  internal: {
    content: string
    contentDigest: string
    mediaType: string
    type: string
  }
}

Nota Bene: Gatsby Version Compatibility

gatsby-source-s3-asset is compatible only with Gatsby V2,