Writing

Caching a dashboard overview with Next.js Cache Components

October 2026 · 9 min read · Next.js, Caching, Architecture

This post is a pattern guide, not a story about a specific production dashboard I operate. It describes how I would mix Next.js Cache Components on an overview page where different regions need different freshness — static chrome, KPIs that can lag a few minutes per organization, charts that can lag longer, and an activity feed that should stay dynamic.

Next.js 16’s model assumes dynamic data by default. You opt regions into caching with the 'use cache' directive and shape lifetime with cacheLife, tags with cacheTag, and targeted invalidation with updateTag from Server Actions. Imports for those helpers come from next/cache per the current docs.

Freshness per region

A useful first step is a table of what the user sees versus how stale it can be:

  • Shell — navigation, layout chrome, empty skeleton shapes: static or long-lived cache.
  • KPI tiles — numbers per organization: cache on the order of minutes; tag by orgId.
  • Charts — aggregated series: cache for hours; separate tags from KPIs so a chart refresh does not flush tiles unnecessarily.
  • Activity feed — recent events: dynamic (no cache) or very short lifetime; always tenant-scoped at fetch time.

The page shell can render immediately from cache while Suspense boundaries stream in heavier regions.

Cached KPI fetch (tenant-safe)

Cached functions must not read cookies or headers inside the cached scope — that would pin the cache to a single user or explode entries. Pass orgId (or another tenant key) as an explicit argument from a parent that already resolved the session.

import { cacheLife, cacheTag } from "next/cache";

export async function getKpiOverview(orgId: string) {
  "use cache";
  cacheLife("minutes");
  cacheTag("dashboard-kpis", `org-${orgId}`);

  // Fetch using orgId — do not call cookies() here
  const res = await fetch(
    `https://api.example.com/orgs/${orgId}/kpis`,
    { next: { tags: [`org-${orgId}-kpis`] } },
  );
  return res.json();
}

Enable Cache Components in next.config when you adopt this model (cacheComponents: true in the Next.js 16 config docs). Without that flag, reach for the older caching APIs instead of copying the directive verbatim.

Invalidation after a write

When a user updates something that affects KPIs, a Server Action can call updateTag so the next navigation sees fresh data (read-your-own-writes).updateTag is only valid inside Server Actions; Route Handlers should use revalidateTag instead.

"use server";

import { updateTag } from "next/cache";

export async function adjustQuota(orgId: string, value: number) {
  await db.quota.update({ where: { orgId }, data: { value } });
  updateTag(`org-${orgId}`);
}

UI composition

Wrap each cached region in a Suspense boundary with a skeleton fallback that matches the shell grid so layout does not jump. Show a subtle “Updated X ago” label from the cached payload’s timestamp if the API returns one — avoid implying real-time precision when the cache lifetime is minutes or hours.

Pair each widget with an error boundary so one failed chart does not blank the whole overview. The feed stays outside long-lived cache unless you are comfortable showing stale events; I usually keep it dynamic and scoped per org at request time.

What I would verify in a spike

  • Cache keys change when orgId changes — no cross-tenant leakage.
  • Mutations call the right tags; KPI and chart tags are not overly broad.
  • Loading and error states match the shell padding rules on real devices.
  • Documentation matches the installed Next.js minor version.

Cache Components are a way to declare intent in the component tree instead of sprinkling revalidate constants on every route segment. The dashboard table above is the map; use cache, cacheLife, and cacheTag are the levers.

← All blog posts