Gatsby Netlify LFS Source Plugin

Host image-heavy Gatsby sites on Netlify for free* using Git LFS & Netlify Large Media.

How it works

The Problem

One of Gatsby’s primary draws is how it handles images with gatsby-plugin-image. Gatsby can also be deployed for free from a git repo via Netlify. Unfortunately, git repos cannot contain large numbers of image or binary files required for an image-heavy Gatsby site. Image-heavy Gatsby sites would then require a content management system (like Netlify CMS, or other Headless CMSs) and possibly paid hosting.

Netlify Hosting with Git LFS

This plugin solves the above problem by storing large files (images and other media) using Git LFS (Large File Storage), and serving those large image files to a Gatsby site via Netlify Large Media. It replaces the need for gatsby-plugin-sharp and gatsby-transformer-sharp with the Netlify LFS Transform Images API by providing an alternate method of creating the image prop for the <GatsbyImage/> component.

Drawbacks

The gastby build command doesn’t have access to the git LFS images at build time. This limitation requires us to preprocess all the build-time data we need from our lfs images, and then commit that data as a file. This file must be regenerated every time an image is added or removed from the LFS tracked repo.

Getting Started

1. Configure Git LFS and Netlify

1. Configure Git LFS by following the “Getting Started” instructions on the linked page.
2. Setup Netlify Large Media by following the instructions on the linked page.

2. Configure the Gatsby Plugin

1. install the plugin

   npm install gatsby-source-netlify-lfs

2. Optionally - create a plugins config in gatsby-config.js. This plugin will work without this config, but this is where overrides can be providied to the netfls script.

   module.exports = {
     plugins: [
       {
         resolve: 'gatsby-source-netlify-lfs',
         options: {
           // 'paths' defaults to include all 'gatsby-source-filesystem' config paths, but they can be manually overridden here
           paths: [
             `${__dirname}/src/blog/images`,
             `${__dirname}/content/images`,
           ],
   
           // limit the formats that are included
           // formats: ['jpg', 'png'], //: ('jpg' | 'jpeg' | 'png' | 'svg' | 'gif')[]
           
           // placeholder type
           // placeholder: 'blurred',  //: 'dominantColor' | 'blurred' | 'none';
           // blurredOptions: {
           //   width: 40,
           //   toFormat: 'jpg',
           // }
         }
       }
     ],
   }

3. Setup a npm script in your package.json to run the netfls preprocess cli script

   {
     "scripts":{
       "netfls": "netfls"
     }
   }

4. npm run netlfs to generate the ./src/netlifyLfs/netlifyLfsImageData.json and commit this file. It’s required by gatsby build when deployed to netlify. This file must be regenerated every time an image is added or removed from the LFS tracked repo. You may want to add this as a pre-commit hook or as part of a watch command.

3. Use with <GatsbyImage/> in React

1. Create a file ./src/netlifyLfs/getNetlifyLfsImage.js that is some version of the example below:

   import { initNetlifyLfsImageData } from "gatsby-source-netlify-lfs";
   import imageData from "./netlifyLfsImageData.json";
   
   /** default IGetNetlifyLfsImageArgs */
   const defaultArgs = {
       // backgroundColor: 'hsl(0deg 0% 1%)',
   };
   
   /** use in place of getImage() from "gatsby-plugin-image" */
   export const getNetlifyLfsImage = initNetlifyLfsImageData(imageData, defaultArgs);

2. Use the exported getNetlifyLfsImage() in place of getImage()

   const ImageExample = (props) => {
     // get the publicURL of the desired image
     const data = useStaticQuery(graphql`{
       exampleImage: file(absolutePath: { regex: "/ExampleImageName.png/" }) { publicURL })
     }`);
     const image = getNetlifyLfsImage({
       publicURL: data.exampleImage.publicURL
       backgroundColor: 'hsl(0deg 0% 1%)',
       // other options - see 'getNetlifyLfsImage args' below
     })
     return (
       <GatsbyImage image={image} alt={'Netlify LFS Example Image'}/>
     )
   }

Docs

gatsby-config.js Options

…later, the only currently supported option is the optional paths array mentioned above. Future options will look like the interface GatsbySourceNetlifyLfsConfig

getNetlifyLfsImage args

…later, see linked typescript def in the meantime: IGetNetlifyLfsImageDataArgs

Contributing

PRs welcome.

TODOs