Getting started with Cache Components

This guide extends the App Router setup. It requires Next.js 16, React 19.1 or later, and React DOM 19.1 or later.

Use the official Next.js caching guide for the full Cache Components model.

Configure Cache Components

Enable Cache Components. Register the Blueprint Auth profile.

next.config.ts

import { createAuthCacheProfiles } from "@krakentech/blueprint-auth";
import type { NextConfig } from "next";
import { authConfig } from "./src/lib/auth/config";

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    ...createAuthCacheProfiles(authConfig),
  },
};

export default nextConfig;

The factory reads the access token refresh threshold from authConfig. Pass the same server-only config to runtime auth.

Profile	stale	revalidate	expire
auth	300 seconds	3600 - accessTokenRefreshThresholdSeconds seconds	3600 seconds

The default threshold is 60 seconds. The default revalidate value is 3540 seconds.

Use this profile only for cache timing. Check access at the request boundary because a stale entry can remain after an access token expires or permissions change.

Keep the request boundary outside the cache

getAuth.* reads request cookies and headers. redirectToLogin also reads request state. Next.js does not allow these calls inside a "use cache" scope.

Use this sequence:

1. Resolve the auth context outside the cached function.
2. Handle a nullable auth context before calling the cached function.
3. Pass the complete auth context object as an argument to the cached function.
4. Use that auth context to construct the matching GraphQL client inside the cached function.

components/UserProfile.tsx

import { BlueprintAuthErrorCode } from "@krakentech/blueprint-auth";
import type { AuthContext } from "@krakentech/blueprint-auth/server";
import { cacheLife } from "next/cache";
import { getAuth, getGraphQLClient, redirectToLogin } from "@/lib/auth/server";
import { ViewerQuery } from "@/queries/viewer";

export async function UserProfile() {
  const auth = await getAuth.user();

  if (!auth) {
    return redirectToLogin({
      errorCode: BlueprintAuthErrorCode.AuthenticationRequired,
    });
  }

  const viewer = await getViewer(auth);
  return <p>Signed in as {viewer.fullName}</p>;
}

async function getViewer(auth: AuthContext.User) {
  "use cache";
  cacheLife("auth");

  const client = getGraphQLClient.user({ auth });
  const { viewer } = await client.request(ViewerQuery);
  return viewer;
}

Render UserProfile inside a Suspense boundary because resolving auth reads request state. The boundary must wrap the component that calls getAuth.user, not just the content returned after that call:

app/profile/page.tsx

import { Suspense } from "react";
import { UserProfile } from "@/components/UserProfile";

export default function ProfilePage() {
  return (
    <Suspense fallback={<p role="status">Loading profile...</p>}>
      <UserProfile />
    </Suspense>
  );
}

A loading.tsx file can provide the boundary for a page and its descendants, but it does not cover request-state reads in the layout above that page.

Use AuthContext.Viewer with getAuth.viewer and getGraphQLClient.viewer when authentication is optional. Use AuthContext.Org with getAuth.org and getGraphQLClient.org for organization operations.

For organization auth, bind an AuthCacheAdapter to the auth factory. User and viewer auth do not require an adapter. The adapter stores organization tokens, not cached query results. It is separate from React's cache function and the Next.js Cache Components storage or cache handler.

Protect credentials

Auth contexts contain credentials. A user context contains an access token. A context can also contain forwarded or custom headers.

Keep every auth context server-only and out of Client Components, browser code, logs, and public props.

Understand the cache key

Pass the complete auth context object as the cached function argument. It provides the credential required to construct the matching GraphQL client. Next.js includes serializable function arguments in the cache key, so the context's access token, client IP, resolved headers, session, and other fields participate in the key.

Proactive refresh happens during auth resolution and outside the cached function. A replacement access token selects a different cache entry.

Next steps

Read the getAuth and getGraphQLClient API reference. Use the v44 migration guide when replacing the removed scoped clients.