Gatsby Netlify LFS Source Plugin

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

How it works

$3

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.

$3

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

$3

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

$3

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.

$3

1. install the plugin
``bash
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.
`js
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
`json
{
"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


1. Create a file ./src/netlifyLfs/getNetlifyLfsImage.js that is some version of the example below:
`js
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()
`jsx
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 (

)
}
`

Docs

$3

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

$3

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

Contributing

PRs welcome.

TODOs