CircleCI npm Maintainability codecov

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).



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: '',
    domain: null, // [optional] Not necessary to define for AWS S3; defaults to ``
    protocol: 'https', // [optional] Default to `https`.
    publicDomain: null, // [optional] Use this domain to construct the public URL for the assets
    accessKeyId: 'your AWS Access Key', // You can also use something like process.env.AWS_ACCESS_KEY
    secretAccessKey: 'Your AWS Secret Access Key',

const plugins = [
  // ...

module.exports = { plugins }


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,