Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
Help Eleventy: Fill out Survey Awesome!
Versions
Stable
3.0.0
Canary
3.0.1-alpha.1
Toggle Menu
Compare npm install
Eleventy 5.81s
Remix 40.14s

Quick Tip: 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

  • Makes at most one network request in the duration time span—save on both your API limit count and your build time!
  • Easy graceful handling of bad network requests to an API.
  • If your cache expires and it makes another request, and that request fails—it automatically falls back to the expired cache entry! This is especially useful if you’re developing without a network connection (airplane-driven-development)—your site will work the same as it did with the network connection—no changes required to your local development environment.

Example

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

import Fetch from "@11ty/eleventy-fetch";

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

	return {
		stargazers: json.stargazers_count,
	};
};
const Fetch = require("@11ty/eleventy-fetch");

module.exports = async function () {
	// https://developer.github.com/v3/repos/#get
	let json = await Fetch("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 hosted build server, it may not maintain updates to the cache and will likely re-run every time. You can learn how to persist this cache on your build server.

Otherwise, current GitHub rate limits are limited to 60 requests per hour, so this will only be a problem if you do more than 60 Netlify builds in an hour. The npm API doesn’t seem to have a hard limit.

Failing Even More Gracefully

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.

import Fetch from "@11ty/eleventy-fetch";

export default 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,
		};
	}
};
const Fetch = 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,
		};
	}
};