Cache Explained: maxAge and Stale in Simple Terms

How long your site keeps a copy of the list (maxAge), what happens after it expires (stale/SWR), when new articles appear, and best practices for Nuxt + microCMS.

Like you're 5

maxAge = “how long we keep the same copy”

  • Your site doesn’t ask microCMS every time someone opens the page.
  • It keeps a copy of the list and uses that copy for a while.
  • maxAge: 1 hour means: “Keep using this same copy for 1 hour.”

So for that list, your site is not looking at microCMS every second; it’s looking at the copy it saved.

So does a new article take 1 hour to appear?

It depends which page we’re talking about.

  1. Page that uses “list-no-stale” (e.g. /news-no-stale)
    • That list is cached for 1 hour.
    • So yes: a new article created in microCMS can take up to 1 hour to show on that page, until the cache expires.
  2. Other pages (e.g. main News or Articles)
    • CDN cache is set to 1 minute (60 seconds).
    • A new article will usually show within about 1 minute, or when someone refreshes / navigates and the app refetches.

So: 1 hour = only for the list-no-stale endpoint. About 1 minute = for the main news/articles lists.

maxAge vs stale in list-no-stale.get.ts

maxAge (e.g. 60×60 = 1 hour)

  • How long the cached response is “fresh” (seconds).
  • While fresh: the handler returns the cache and does not call microCMS.
  • After that: the cache is expired.

stale (controlled by swr)

  • What happens after the cache is expired:
    • swr: true (default): “Stale-while-revalidate” — server can still send the old (stale) response and fetch new data in the background. User might see old content for one more request.
    • swr: false (list-no-stale): Server does not serve that stale response; the next request waits for a fresh fetch from microCMS.

In list-no-stale: maxAge = use cache for 1 hour. stale = when that 1 hour is over, never send the old cache; always wait for fresh data (swr: false).

Common best practices for articles/news (Nuxt 4, NuxtHub, MicroCMS)

  • List/detail APIs: Cache so you don’t hit microCMS every request. Prefer short maxAge (e.g. 1–5 min) or SWR so the site stays fast but content can update.
  • Stale-while-revalidate: For articles/news, keep swr: true (Nitro default) and maxAge around 60–300 seconds. Users get a fast response; next request gets fresh data after revalidation.
  • Webhooks: When content is published/updated in MicroCMS, call a webhook to invalidate or clear the cache so new articles appear quickly even with longer maxAge.
  • Frontend (Nuxt 4): Use useFetch with a stable key and call refresh() when the user navigates to the list/detail page so they see updates without a full reload.
  • CDN: Set Cache-Control on API routes (e.g. short s-maxage). Use stale-while-revalidate at the CDN for “fast + eventually fresh” behavior.

In practice: List/detail — cache with short maxAge and SWR on. “No stale” comparison — use maxAge + swr: false like list-no-stale. Faster updates after publish — add a MicroCMS webhook that clears cache when content changes.

← Back to News