The Equal Justice Initiative
Eleventy
The possum is Eleventy’s mascot
Eleventy Documentation
Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Quick Tip #009—Cache Data Requests

INFO:
Read the full documentation at the eleventy-fetch plugin page.

In Quick Tip #007, we described a method to fetch data from an API at build time (in this example it was GitHub Stargazers) to display on your site.

However, if you’re working on your site locally, you probably don’t want every Eleventy build to make a request to an external API call. You’d hit the rate limit pretty quickly (on GitHub, 60 per hour) and each request would slow down your build times!

Now there is an easier way. You can use the eleventy-fetch utility to cache these requests to save on both API limits and build performance!

npm install @11ty/eleventy-fetch

Features Jump to heading

Example Jump to heading

This code is currently in use on the Eleventy web site to display GitHub stars in the footer. Check out the full source code.

Filename _data/github.js
const EleventyFetch = require("@11ty/eleventy-fetch");

module.exports = async function() {
  // https://developer.github.com/v3/repos/#get
  let json = await EleventyFetch("https://api.github.com/repos/11ty/eleventy", {
    duration: "1d", // 1 day
    type: "json" // also supports "text" or "buffer"
  });

  return {
    stargazers: json.stargazers_count
  };
};
INFO:
Take note that if you’re using this on a Netlify build, it will not maintain updates to the cache (as it resets the cache to the files that are checked into git) and will likely re-run every time.

Failing Even More Gracefully Jump to heading

Wrap the above code in a nice try catch allows you to return a fake data set if the very first request fails (no expired cache entry is available). Note that if there is already an expired cache entry available, we use that instead.

const EleventyFetch = require("@11ty/eleventy-fetch");

module.exports = async function() {
  try {
    // https://developer.github.com/v3/repos/#get
    let json = await EleventyFetch("https://api.github.com/repos/11ty/eleventy", {
      duration: "1d", // 1 day
      type: "json" // also supports "text" or "buffer"
    });

    return {
      stargazers: json.stargazers_count
    };
  } catch(e) {
    console.log( "Failed getting GitHub stargazers count, returning 0" );
    return {
      stargazers: 0
    };
  }
};