{"id":13632705,"url":"https://github.com/jessestuart/gatsby-source-s3-image","last_synced_at":"2025-06-15T13:40:28.718Z","repository":{"id":31875130,"uuid":"119328941","full_name":"jessestuart/gatsby-source-s3-image","owner":"jessestuart","description":"GatsbyJS plugin to source images from S3-compliant APIs, with EXIF-extracting superpowers.","archived":false,"fork":false,"pushed_at":"2024-06-07T14:26:40.000Z","size":7076,"stargazers_count":35,"open_issues_count":71,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-22T03:26:59.223Z","etag":null,"topics":["exif","gatsby","gatsby-plugin","gatsby-source","gatsbyjs","photography","s3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jessestuart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-29T03:51:48.000Z","updated_at":"2023-08-18T14:59:51.000Z","dependencies_parsed_at":"2024-06-18T19:51:19.650Z","dependency_job_id":"17449f58-8102-40d2-9f5e-0508043180ca","html_url":"https://github.com/jessestuart/gatsby-source-s3-image","commit_stats":{"total_commits":1549,"total_committers":6,"mean_commits":258.1666666666667,"dds":"0.28663653970303427","last_synced_commit":"3d1028f861395de71d2cf8f3c387eee25db0a881"},"previous_names":[],"tags_count":443,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessestuart%2Fgatsby-source-s3-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessestuart%2Fgatsby-source-s3-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessestuart%2Fgatsby-source-s3-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessestuart%2Fgatsby-source-s3-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jessestuart","download_url":"https://codeload.github.com/jessestuart/gatsby-source-s3-image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222144104,"owners_count":16938448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exif","gatsby","gatsby-plugin","gatsby-source","gatsbyjs","photography","s3"],"created_at":"2024-08-01T22:03:11.524Z","updated_at":"2024-10-30T01:04:01.932Z","avatar_url":"https://github.com/jessestuart.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://gatsbyjs.org\"\u003e\n    \u003cimg src=\"./assets/logo.svg\" width=\"100\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003e\n  gatsby-source-s3-image\n\u003c/h1\u003e\n\n[![CircleCI][circleci-badge]][circleci-link] [![npm][npm-badge]][npm-link]\n[![Maintainability][codeclimate]][codeclimate 2]\n[![codecov][codecov]][codecov 2]\n\n## What is this?\n\n`gatsby-source-s3-image` is a [GatsbyJS][github] _Source_ plugin for\n**converting images from any S3-compliant API[1] into GatsbyJS nodes**.\n\n[1] This includes AWS S3, of course, as well as third-party solutions like\nDigital Ocean Spaces, or open source / self-hosted products like [MinIO][min].\n\n### But I can just query S3 manually client-side...\n\nSure, knock yourself out. But there are a few benefits you get out-of-the-box\nwith this package:\n\n- Native integration with Gatsby's GraphQL data ontology, of course. You just\n  provide the bucket details (and IAM credentials, if not public, which is\n  recommended).\n- Several other benefits come with this tight integration with Gatsby API's,\n  such as intelligent caching (nobody wants to wind up with an unexpected S3\n  bill as your CI server happily churns out builds, amiright?); automatic image\n  asset optimization thanks to `gatsby-image`, etc.\n- And to top things off — `gatsby-source-s3-image` will **automatically detect\n  and extract image EXIF metadata from your photos**, and expose this data at\n  the GraphQL layer as node fields.\n\n### Tell me more about this EXIF stuff.\n\nCurrently supported EXIF fields that are automatically extracted when available\ninclude:\n\n- `DateCreatedISO` (`string`)\n- `DateTimeOriginal` (`number`)\n- `ExposureTime` (`number`)\n- `FNumber` (`number`)\n- `FocalLength` (`number`)\n- `ISO` (`number`)\n- `LensModel` (`string`)\n- `Model` (`string`)\n- `ShutterSpeedValue` (`number`)\n\nThese fields are properties of the \"wrapper\" node, `S3ImageAsset`. This type\ncomposes the `ImageSharp` node, the `File` node representing the cached image on\ndisk (fetched via the `RemoteFileNode` API), and lastly the extracted EXIF data.\nAs a result, you can easily retrieve both a set of images as well as any subset\nof their associated metadata in a single request — or just the metadata by\nitself, if that's all you need. For example:\n\n```es6\nexport const pageQuery = graphql`\n  query PhotographyPostsQuery {\n    allS3ImageAsset {\n      edges {\n        node {\n          id\n          EXIF {\n            DateCreatedISO\n            ExposureTime\n            FNumber\n            ShutterSpeedValue\n          }\n          childrenFile {\n            childImageSharp {\n              original {\n                height\n                width\n              }\n              thumbnailSizes: fluid(maxWidth: 256) {\n                aspectRatio\n                src\n                srcSet\n                sizes\n              }\n              largeSizes: fluid(maxWidth: 1024) {\n                aspectRatio\n                src\n                srcSet\n                sizes\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n`\n```\n\n## Usage\n\n### Setup\n\nAdd the dependency to your `package.json`:\n\n```console\n$ yarn add gatsby-source-s3-image\n$ # Or:\n$ npm install --save gatsby-source-s3-image\n```\n\nNext, register the plugin with the GatsbyJS runtime in the `plugins` field\nexported from your `gatsby-config.js` file, filling in the values to point to\nwherever your bucket is hosted:\n\n```es6\nconst sourceS3 = {\n  resolve: 'gatsby-source-s3-image',\n  options: {\n    bucketName: 'jesse.pics',\n    domain: null, // [optional] Not necessary to define for AWS S3; defaults to `s3.amazonaws.com`\n    protocol: 'https', // [optional] Default to `https`.\n  },\n}\n\nconst plugins = [\n  sourceS3,\n  // ...\n]\n\nmodule.exports = { plugins }\n```\n\n## Querying\n\nAs mentioned above, `gatsby-source-s3-image` exposes nodes of type\n`S3ImageAsset`:\n\n```typescript\ninterface S3ImageAssetNode {\n  id: string\n  absolutePath: string\n  ETag: string\n  Key: string\n  EXIF: ExifData | undefined // ExifData is defined below --\u003e\n  internal: {\n    content: string\n    contentDigest: string\n    mediaType: string\n    type: string\n  }\n}\n\ninterface ExifData {\n  DateCreatedISO: string\n  DateTimeOriginal: number\n  ExposureTime: number\n  FNumber: number\n  FocalLength: number\n  ISO: number\n  LensModel: string\n  Model: string\n  ShutterSpeedValue: number\n}\n```\n\nNot only can this be used to populate page data, I've found it useful in\nbootstrapping the pages themselves, e.g., to programmatically create dynamic\nPhoto Gallery pages at build time depending on the contents of a bucket. For\nexample:\n\n```typescript\n// In `gatsby-node.js` -- using a query like this:\nconst photographyQuery = graphql`\n  {\n    allS3ImageAsset {\n      edges {\n        node {\n          ETag\n          EXIF {\n            DateCreatedISO\n          }\n        }\n      }\n    }\n  }\n`\n\n// We can then dynamically generate pages based on EXIF data, like this:\nconst createPages = ({ actions }) =\u003e {\n  const { createPage } = actions\n  const photographyTemplate = path.resolve(\n    './src/templates/photography-post.js'\n  )\n\n  const createPhotographyPosts = edges =\u003e {\n    // Create the photography \"album\" pages -- these are a collection of photos\n    // grouped by ISO date.\n    const imagesGroupedByDate = _.groupBy(edges, 'node.EXIF.DateCreatedISO')\n    _.each(imagesGroupedByDate, (images, date) =\u003e {\n      createPage({\n        path: `/photography/${date}`,\n        component: photographyTemplate,\n        context: {\n          name: date,\n          datetime: DateTime.fromISO(date),\n          type: PageType.Photography,\n        },\n      })\n    })\n  }\n}\n```\n\n## _Nota Bene:_ Gatsby Version Compatibility\n\n`gatsby-source-s3-image` was recently [updated][github 2] to support Gatsby V2,\nwhich required some breaking changes. The Gatsby V1-compatible version of the\nplugin is still fully functional, and will continue to receive maintenance\nupdates as necessary. The last release compatible with Gatsby V1 can be found\n[here][github 3].\n\n[circleci-badge]: https://circleci.com/gh/jessestuart/gatsby-source-s3-image.svg?style=shield\n[circleci-link]: https://circleci.com/gh/jessestuart/gatsby-source-s3-image\n[codeclimate]: https://api.codeclimate.com/v1/badges/4488634e45e84d3cbdbe/maintainability\n[codeclimate 2]: https://codeclimate.com/github/jessestuart/gatsby-source-s3-image/maintainability\n[codecov]: https://codecov.io/gh/jessestuart/gatsby-source-s3-image/branch/master/graph/badge.svg\n[codecov 2]: https://codecov.io/gh/jessestuart/gatsby-source-s3-image\n[github]: https://github.com/gatsbyjs/gatsby\n[github 2]: https://github.com/jessestuart/gatsby-source-s3-image/pull/238\n[github 3]: https://github.com/jessestuart/gatsby-source-s3-image/releases/tag/v0.2.133\n[min]: https://min.io\n[npm-badge]: https://img.shields.io/npm/v/gatsby-source-s3-image.svg\n[npm-link]: https://www.npmjs.com/package/gatsby-source-s3-image\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessestuart%2Fgatsby-source-s3-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjessestuart%2Fgatsby-source-s3-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessestuart%2Fgatsby-source-s3-image/lists"}