Netlify Large Media works by essentially mirroring Git LFS’s behavior, but with a few key differences that make it seamless for Netlify deployments.
Imagine you’re building a website for a photography portfolio. You’ve got hundreds of high-resolution images, each several megabytes in size. If you commit these directly to your Git repository, your repo will balloon in size, clone times will skyrocket, and your build process will grind to a halt. This is where Git Large File Storage (LFS) and, by extension, Netlify Large Media come in.
Git LFS replaces large files in your Git repository with small text pointers. The actual large files are stored separately on an LFS server. When you clone the repository, Git LFS downloads only the pointer files. During the build process, Git LFS (or Netlify’s integration) fetches the actual large files needed for your build.
Here’s a simplified look at how it plays out during a Netlify build:
- Git Checkout: Netlify’s build environment checks out your repository. It retrieves the pointer files for your large media assets.
- LFS Pointer Detection: Netlify’s build image has Git LFS pre-installed. It detects these pointer files.
- Asset Fetching: Netlify then communicates with its own Large Media storage (which is essentially an LFS server) to download the actual binary files corresponding to those pointers. This happens before your build command runs.
- Build Execution: Your build command (e.g.,
npm run build,hugo) then executes. Your project now has access to the actual large media files, and your build process can use them as if they were directly in the repository. - Deployment: The built assets, including the large media files, are then deployed to Netlify’s CDN.
Let’s see this in action. Suppose you have an image named hero-background.jpg that’s 10MB.
Without Netlify Large Media (and Git LFS):
If you git add hero-background.jpg and git commit, that 10MB file is part of your Git commit history. Your .git directory grows.
With Netlify Large Media (and Git LFS):
First, you’d install Git LFS locally:
git lfs install
Then, you’d tell Git LFS to track specific file types, like JPEGs:
git lfs track "*.jpg"
This creates a .gitattributes file. Make sure to commit this:
git add .gitattributes
git commit -m "Configure Git LFS for JPGs"
Now, when you add your large hero-background.jpg:
git add hero-background.jpg
git commit -m "Add hero background image"
Instead of the 10MB image being committed, Git LFS stores a pointer file (e.g., hero-background.jpg.git-lfs which is ~100 bytes) in your Git repository. The actual 10MB file is uploaded to a separate LFS store (in Netlify’s case, this is their managed Large Media storage).
When Netlify builds your site, it automatically detects the .gitattributes file and the LFS pointers. It then downloads the 10MB hero-background.jpg from its Large Media store before running your build command.
The core problem Netlify Large Media solves is managing large binary assets within a Git workflow without compromising the performance and integrity of your Git repository. It allows you to keep your Git repo lean and fast while still having your large assets available for your build process.
The exact levers you control are primarily through your .gitattributes file. This file is crucial. It dictates which files Git LFS should manage. A common mistake is forgetting to commit .gitattributes after running git lfs track, which means Netlify won’t know to fetch those files.
What most people don’t realize is that Netlify actually provides a generous free tier for Large Media storage and bandwidth, which is often sufficient for many projects. You only start incurring costs when you exceed those limits, and even then, it’s typically very affordable. It’s not just for enterprise-level projects.
The next thing you’ll likely encounter is handling asset transformations, like image resizing or format conversion, directly within Netlify’s build process using these large media files.