What is blocking fallback in getStaticPaths and when it should be used?

Why was fallback: 'blocking' introduced? 🤔🤔

When Vercel released the 9.3 version of their popular Next.js framework, two brand new data fetching methods were introduced: getStaticProps and getServerSideProps.

If you want to use getStaticProps with, for example, a detail page of a product (pages/products/[id].js) you use getStaticPaths along with getStaticProps to define which product IDs you want to generate the page for.

If, however, you have a large e-commerce site with 10,000 products, you wouldn't want to return the IDs of all products from the getStaticPaths as building 10,000 pages would take ages.

Instead, you might just return the IDs of the most popular products and use fallback: true in getStaticPaths.

If you then a product page of some obscure product that's not frequently visited (e. g. /products/43284) for the first time, you'd be presented with a loading screen 💻 before the page gets generated (and the product data is fetched in getStaticProps).

(If you don't want to fetch other products than you specified, use fallback: false and Next.js will return a 404 🛑 for those pages.)

Every subsequent visit will serve the page statically 🚀 as the page is built (and cached) on the first visit.

However, having to use the loading indicator during the first visit has some issues:

• Some og:* crawlers (Facebook, Twitter, LinkedIn, ...) don't support JS and thus fail to fetch correct og:* tags for fallback: true pages
• AMP pages 📲 don't work correctly with fallback: true as they get stuck loading. (https://github.com/vercel/next.js/issues/14256)

Therefore, the Next.js team introduced a third option for the fallback field: 'blocking'.

(See https://github.com/vercel/next.js/issues/15637)

How does fallback: 'blocking' work? 😲😲

If you're using fallback: true in your page, you have to use something like this in your code 😕:

const router = useRouter();

if (router.isFallback) {
  return <Loading />;
}

return <ProductDetail product={product} />;

This is for the case when the user visits a page with fallback: true for the first time (a page which has not yet been built and whose props from getStaticProps hasn't been fetched).

If, however, you use fallback: 'blocking' in getStaticPaths, you don't use the if (router.isFallback) check. That's because when the user visits a page with fallback: 'blocking' which has not yet been built, Next.js is first going to build the page and only after it's built it's going the send the response to the user's browser.

You can play ▶️ with the CodeSandbox below the see how fallback: false, fallback: true, and fallback: 'blocking' differ.

When (not) to use fallback: 'blocking'?

Generally, the Next.js team encourages you not to use it unless is necessary. Using fallback: 'blocking' doesn't help the SEO (as Google and other search engine crawlers run JS code and will wait for a fallback: true page to load). Using fallback: 'blocking' makes the user wait 🥱 without any response while the page is being built and it's better to use fallback: true and show a loading skeleton while the page is being built instead.

If, however, you're experiencing issues with OG tags, AMP, or something else due to the usage of fallback: true, feel free to switch to fallback: 'blocking' 🤗.

You can see the comparison between fallback: false, fallback: true, and fallback: blocking below: ⬇️⬇️⬇️

fallback: false

fallback: true

fallback: 'blocking'