feat(core): wrap layout-level guest queries in unstable_cache

Wrap home page, header, footer, SEO canonical, reCAPTCHA, and root
layout metadata queries in unstable_cache for guest visitors.
Authenticated requests continue to bypass the cache with no-store.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jorgemoya

.changeset/guest-cache-layout.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Wrap layout-level guest queries (home page, header, footer, SEO canonical, reCAPTCHA, root layout metadata) in `unstable_cache` with configurable revalidation. Authenticated requests continue to bypass the cache.

core/app/[locale]/(default)/page-data.ts

@@ -1,3 +1,4 @@
+import { unstable_cache } from 'next/cache';
 import { cache } from 'react';
 
 import { client } from '~/client';
@@ -77,15 +78,35 @@ const HomePageQuery = graphql(
   [FeaturedProductsCarouselFragment, FeaturedProductsListFragment],
 );
 
-export const getPageData = cache(
-  async (currencyCode?: CurrencyCode, customerAccessToken?: string) => {
+const getCachedPageData = unstable_cache(
+  async (locale: string, currencyCode?: CurrencyCode) => {
     const { data } = await client.fetch({
       document: HomePageQuery,
-      customerAccessToken,
       variables: { currencyCode },
-      fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
+      locale,
+      fetchOptions: { cache: 'no-store' },
     });
 
     return data;
   },
+  ['home-page-data'],
+  { revalidate },
+);
+
+export const getPageData = cache(
+  async (locale: string, currencyCode?: CurrencyCode, customerAccessToken?: string) => {
+    if (customerAccessToken) {
+      const { data } = await client.fetch({
+        document: HomePageQuery,
+        customerAccessToken,
+        variables: { currencyCode },
+        locale,
+        fetchOptions: { cache: 'no-store' },
+      });
+
+      return data;
+    }
+
+    return getCachedPageData(locale, currencyCode);
+  },
 );

core/app/[locale]/(default)/page.tsx

@@ -38,7 +38,7 @@ export default async function Home({ params }: Props) {
     const customerAccessToken = await getSessionCustomerAccessToken();
     const currencyCode = await getPreferredCurrencyCode();
 
-    return getPageData(currencyCode, customerAccessToken);
+    return getPageData(locale, currencyCode, customerAccessToken);
   });
 
   const streamableFeaturedProducts = Streamable.from(async () => {

core/app/[locale]/layout.tsx

@@ -1,6 +1,7 @@
 import { Analytics } from '@vercel/analytics/react';
 import { SpeedInsights } from '@vercel/speed-insights/next';
 import type { Metadata } from 'next';
+import { unstable_cache } from 'next/cache';
 import { notFound } from 'next/navigation';
 import { NextIntlClientProvider } from 'next-intl';
 import { setRequestLocale } from 'next-intl/server';
@@ -53,15 +54,29 @@ const RootLayoutMetadataQuery = graphql(
   [WebAnalyticsFragment, ScriptsFragment],
 );
 
-const fetchRootLayoutMetadata = cache(async () => {
-  return await client.fetch({
-    document: RootLayoutMetadataQuery,
-    fetchOptions: { next: { revalidate } },
-  });
+const getCachedRootLayoutMetadata = unstable_cache(
+  async (locale: string) => {
+    return await client.fetch({
+      document: RootLayoutMetadataQuery,
+      locale,
+      fetchOptions: { cache: 'no-store' },
+    });
+  },
+  ['root-layout-metadata'],
+  { revalidate },
+);
+
+const fetchRootLayoutMetadata = cache(async (locale: string) => {
+  return getCachedRootLayoutMetadata(locale);
 });
 
-export async function generateMetadata(): Promise<Metadata> {
-  const { data } = await fetchRootLayoutMetadata();
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}): Promise<Metadata> {
+  const { locale } = await params;
+  const { data } = await fetchRootLayoutMetadata(locale);
 
   const storeName = data.site.settings?.storeName ?? '';
 
@@ -119,7 +134,7 @@ interface Props extends PropsWithChildren {
 export default async function RootLayout({ params, children }: Props) {
   const { locale } = await params;
 
-  const rootData = await fetchRootLayoutMetadata();
+  const rootData = await fetchRootLayoutMetadata(locale);
   const toastNotificationCookieData = await getToastNotification();
 
   if (!routing.locales.includes(locale)) {

core/components/footer/index.tsx

@@ -6,7 +6,8 @@ import {
   SiX,
   SiYoutube,
 } from '@icons-pack/react-simple-icons';
-import { getTranslations } from 'next-intl/server';
+import { unstable_cache } from 'next/cache';
+import { getLocale, getTranslations } from 'next-intl/server';
 import { cache, JSX } from 'react';
 
 import { Streamable } from '@/vibes/soul/lib/streamable';
@@ -46,34 +47,63 @@ const socialIcons: Record<string, { icon: JSX.Element }> = {
   YouTube: { icon: <SiYoutube title="YouTube" /> },
 };
 
-const getFooterSections = cache(
-  async (customerAccessToken?: string, currencyCode?: CurrencyCode) => {
+const getCachedFooterSections = unstable_cache(
+  async (locale: string, currencyCode?: CurrencyCode) => {
     const { data: response } = await client.fetch({
       document: GetLinksAndSectionsQuery,
-      customerAccessToken,
       variables: { currencyCode },
-      // Since this query is needed on every page, it's a good idea not to validate the customer access token.
-      // The 'cache' function also caches errors, so we might get caught in a redirect loop if the cache saves an invalid token error response.
+      locale,
       validateCustomerAccessToken: false,
-      fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
+      fetchOptions: { cache: 'no-store' },
     });
 
     return readFragment(FooterSectionsFragment, response).site;
   },
+  ['footer-sections'],
+  { revalidate },
 );
 
-const getFooterData = cache(async () => {
-  const { data: response } = await client.fetch({
-    document: LayoutQuery,
-    fetchOptions: { next: { revalidate } },
-  });
+const getFooterSections = cache(
+  async (locale: string, customerAccessToken?: string, currencyCode?: CurrencyCode) => {
+    if (customerAccessToken) {
+      const { data: response } = await client.fetch({
+        document: GetLinksAndSectionsQuery,
+        customerAccessToken,
+        variables: { currencyCode },
+        locale,
+        validateCustomerAccessToken: false,
+        fetchOptions: { cache: 'no-store' },
+      });
+
+      return readFragment(FooterSectionsFragment, response).site;
+    }
+
+    return getCachedFooterSections(locale, currencyCode);
+  },
+);
+
+const getCachedFooterData = unstable_cache(
+  async (locale: string) => {
+    const { data: response } = await client.fetch({
+      document: LayoutQuery,
+      locale,
+      fetchOptions: { cache: 'no-store' },
+    });
+
+    return readFragment(FooterFragment, response).site;
+  },
+  ['footer-data'],
+  { revalidate },
+);
 
-  return readFragment(FooterFragment, response).site;
+const getFooterData = cache(async (locale: string) => {
+  return getCachedFooterData(locale);
 });
 
 export const Footer = async () => {
   const t = await getTranslations('Components.Footer');
-  const data = await getFooterData();
+  const locale = await getLocale();
+  const data = await getFooterData(locale);
 
   const logo = data.settings ? logoTransformer(data.settings) : '';
 
@@ -96,7 +126,7 @@ export const Footer = async () => {
   const streamableSections = Streamable.from(async () => {
     const customerAccessToken = await getSessionCustomerAccessToken();
     const currencyCode = await getPreferredCurrencyCode();
-    const sectionsData = await getFooterSections(customerAccessToken, currencyCode);
+    const sectionsData = await getFooterSections(locale, customerAccessToken, currencyCode);
 
     return [
       {

core/components/header/index.tsx

@@ -1,3 +1,4 @@
+import { unstable_cache } from 'next/cache';
 import { getLocale, getTranslations } from 'next-intl/server';
 import { cache } from 'react';
 
@@ -47,34 +48,64 @@ const getCartCount = cache(async (cartId: string, customerAccessToken?: string)
   return response.data.site.cart?.lineItems.totalQuantity ?? null;
 });
 
-const getHeaderLinks = cache(async (customerAccessToken?: string, currencyCode?: CurrencyCode) => {
-  const { data: response } = await client.fetch({
-    document: GetLinksAndSectionsQuery,
-    customerAccessToken,
-    variables: { currencyCode },
-    // Since this query is needed on every page, it's a good idea not to validate the customer access token.
-    // The 'cache' function also caches errors, so we might get caught in a redirect loop if the cache saves an invalid token error response.
-    validateCustomerAccessToken: false,
-    fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
-  });
-
-  return readFragment(HeaderLinksFragment, response).site;
-});
-
-const getHeaderData = cache(async () => {
-  const { data: response } = await client.fetch({
-    document: LayoutQuery,
-    fetchOptions: { next: { revalidate } },
-  });
+const getCachedHeaderLinks = unstable_cache(
+  async (locale: string, currencyCode?: CurrencyCode) => {
+    const { data: response } = await client.fetch({
+      document: GetLinksAndSectionsQuery,
+      variables: { currencyCode },
+      locale,
+      validateCustomerAccessToken: false,
+      fetchOptions: { cache: 'no-store' },
+    });
+
+    return readFragment(HeaderLinksFragment, response).site;
+  },
+  ['header-links'],
+  { revalidate },
+);
+
+const getHeaderLinks = cache(
+  async (locale: string, customerAccessToken?: string, currencyCode?: CurrencyCode) => {
+    if (customerAccessToken) {
+      const { data: response } = await client.fetch({
+        document: GetLinksAndSectionsQuery,
+        customerAccessToken,
+        variables: { currencyCode },
+        locale,
+        validateCustomerAccessToken: false,
+        fetchOptions: { cache: 'no-store' },
+      });
+
+      return readFragment(HeaderLinksFragment, response).site;
+    }
 
-  return readFragment(HeaderFragment, response).site;
+    return getCachedHeaderLinks(locale, currencyCode);
+  },
+);
+
+const getCachedHeaderData = unstable_cache(
+  async (locale: string) => {
+    const { data: response } = await client.fetch({
+      document: LayoutQuery,
+      locale,
+      fetchOptions: { cache: 'no-store' },
+    });
+
+    return readFragment(HeaderFragment, response).site;
+  },
+  ['header-data'],
+  { revalidate },
+);
+
+const getHeaderData = cache(async (locale: string) => {
+  return getCachedHeaderData(locale);
 });
 
 export const Header = async () => {
   const t = await getTranslations('Components.Header');
   const locale = await getLocale();
 
-  const data = await getHeaderData();
+  const data = await getHeaderData(locale);
 
   const logo = data.settings ? logoTransformer(data.settings) : '';
 
@@ -101,7 +132,8 @@ export const Header = async () => {
     ]);
     // const customerAccessToken = await getSessionCustomerAccessToken();
     // const currencyCode = await getPreferredCurrencyCode();
-    const categoryTree = (await getHeaderLinks(customerAccessToken, currencyCode)).categoryTree;
+    const headerLinks = await getHeaderLinks(locale, customerAccessToken, currencyCode);
+    const categoryTree = headerLinks.categoryTree;
 
     /**  To prevent the navigation menu from overflowing, we limit the number of categories to 6.
    To show a full list of categories, modify the `slice` method to remove the limit.
@@ -128,8 +160,8 @@ export const Header = async () => {
       getSessionCustomerAccessToken(),
       getPreferredCurrencyCode(),
     ]);
-    const giftCertificateSettings = (await getHeaderLinks(customerAccessToken, currencyCode))
-      .settings?.giftCertificates;
+    const headerLinksData = await getHeaderLinks(locale, customerAccessToken, currencyCode);
+    const giftCertificateSettings = headerLinksData.settings?.giftCertificates;
 
     return giftCertificateSettings?.isEnabled ?? false;
   });

core/lib/recaptcha.ts

@@ -1,5 +1,6 @@
 import 'server-only';
 
+import { unstable_cache } from 'next/cache';
 import { cache } from 'react';
 
 import { client } from '~/client';
@@ -24,22 +25,30 @@ export const ReCaptchaSettingsQuery = graphql(`
   }
 `);
 
-export const getReCaptchaSettings = cache(async (): Promise<ReCaptchaSettings | null> => {
-  const { data } = await client.fetch({
-    document: ReCaptchaSettingsQuery,
-    fetchOptions: { next: { revalidate } },
-  });
+const getCachedReCaptchaSettings = unstable_cache(
+  async (): Promise<ReCaptchaSettings | null> => {
+    const { data } = await client.fetch({
+      document: ReCaptchaSettingsQuery,
+      fetchOptions: { cache: 'no-store' },
+    });
 
-  const reCaptcha = data.site.settings?.reCaptcha;
+    const reCaptcha = data.site.settings?.reCaptcha;
 
-  if (!reCaptcha?.siteKey) {
-    return null;
-  }
+    if (!reCaptcha?.siteKey) {
+      return null;
+    }
 
-  return {
-    isEnabledOnStorefront: reCaptcha.isEnabledOnStorefront,
-    siteKey: reCaptcha.siteKey,
-  };
+    return {
+      isEnabledOnStorefront: reCaptcha.isEnabledOnStorefront,
+      siteKey: reCaptcha.siteKey,
+    };
+  },
+  ['recaptcha-settings'],
+  { revalidate },
+);
+
+export const getReCaptchaSettings = cache(async (): Promise<ReCaptchaSettings | null> => {
+  return getCachedReCaptchaSettings();
 });
 
 export const getRecaptchaSiteKey = cache(async (): Promise<string | undefined> => {