Next.js SSR and caching

// lib/catalog.ts: server code only (Server Components, route handlers,
// getServerSideProps). A server key, from a variable without NEXT_PUBLIC_,
// so it never reaches the browser bundle.
import { createServerCatalogClient } from '@usethrottle/catalog/server';

export const catalog = createServerCatalogClient({
  publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
  // Every catalog read is cached by Next.js for 5 minutes, under the
  // throttle-catalog tags. The default is 60 seconds.
  next: { revalidate: 300 },
});

// app/providers.tsx, rendered by app/layout.tsx around the page.
'use client';
import type { ReactNode } from 'react';
import { createCatalogClient } from '@usethrottle/catalog';
import { CatalogProvider } from '@usethrottle/catalog/react';

// In the browser: a browser key, with your site's origins as its allowed
// websites. It is public by design.
const catalog = createCatalogClient({
  publishableKey: process.env.NEXT_PUBLIC_CATALOG_BROWSER_KEY ?? '',
});

export function Providers({ children }: { children: ReactNode }) {
  return <CatalogProvider client={catalog}>{children}</CatalogProvider>;
}

// app/products/[handle]/page.tsx (Next.js 15, App Router)
import { notFound, permanentRedirect } from 'next/navigation';
import { isCatalogError } from '@usethrottle/catalog';
import { catalogTags, staticProductParams } from '@usethrottle/catalog/server';
import { catalog } from '@/lib/catalog';

// Builds up to 1,000 product pages ahead; the others render on first visit.
export function generateStaticParams() {
  return staticProductParams(catalog, { limit: 1000 });
}

async function load(handle: string) {
  try {
    // A per-call `next` replaces the client's, so keep the route's own tags.
    return await catalog.products.get(handle, {
      next: { revalidate: 600, tags: catalogTags('product', handle) },
    });
  } catch (error) {
    if (isCatalogError(error) && error.code === 'NOT_FOUND') notFound();
    throw error;
  }
}

export default async function ProductPage({ params }: { params: Promise<{ handle: string }> }) {
  const { handle } = await params;
  const answer = await load(handle);
  if ('redirectTo' in answer) permanentRedirect(`/products/${answer.redirectTo}`);

  const { product } = answer;
  return (
    <main>
      <h1>{product.title}</h1>
      {product.variants.map((variant) => (
        <p key={variant.sku}>
          {variant.title}: {variant.priceMinor} {variant.currency}
          {variant.lowStock ? ' (only a few left)' : ''}
        </p>
      ))}
    </main>
  );
}

// app/api/catalog-sync/route.ts: call it every minute from a cron job.
import { revalidateTag } from 'next/cache';
import { syncCatalogGeneration } from '@usethrottle/catalog/server';
import { catalog } from '@/lib/catalog';

// Kept in memory here for brevity. On a serverless host each cold instance
// starts empty and its first call only records the generation, so keep it in
// KV or a database row instead; the pages' revalidate time still bounds how
// stale they get when a change is missed.
let previous: number | undefined;

export async function GET(request: Request) {
  if (request.headers.get('authorization') !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response(null, { status: 401 });
  }
  // Reads /config uncached and compares generations, never clocks.
  const { generation, changed } = await syncCatalogGeneration({
    client: catalog,
    previous,
    onChange: () => revalidateTag('throttle-catalog'),
  });
  previous = generation;
  return Response.json({ generation, changed });
}

// app/sitemap.ts
import type { MetadataRoute } from 'next';
import {
  listAllCategoryHandles,
  listAllCollectionHandles,
  listAllProductHandles,
} from '@usethrottle/catalog/server';
import { catalog } from '@/lib/catalog';

const SITE = 'https://shop.example.com';
export const revalidate = 3600;

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const urls: MetadataRoute.Sitemap = [];
  // Public products only, 100 per request, at most 50,000 by default.
  for await (const handle of listAllProductHandles(catalog)) {
    urls.push({ url: `${SITE}/products/${encodeURIComponent(handle)}` });
  }
  for await (const handle of listAllCollectionHandles(catalog)) {
    urls.push({ url: `${SITE}/collections/${encodeURIComponent(handle)}` });
  }
  for (const handle of await listAllCategoryHandles(catalog)) {
    urls.push({ url: `${SITE}/categories/${encodeURIComponent(handle)}` });
  }
  return urls;
}

// pages/categories/[handle].tsx (Next.js 15, Pages Router). pages/_app.tsx
// wraps every page in a <CatalogProvider> with the browser key.
import type { GetServerSideProps, InferGetServerSidePropsType } from 'next';
import type { StorefrontListAnswer } from '@usethrottle/catalog';
import { useProducts } from '@usethrottle/catalog/react';
import { catalog } from '@/lib/catalog';

type Props = { handle: string; initial: StorefrontListAnswer };

// On the server, with the server key. Code used only here never reaches
// the browser bundle.
export const getServerSideProps: GetServerSideProps<Props> = async ({ params }) => {
  const handle = String(params?.handle ?? '');
  const initial = await catalog.products.list({ category: handle, limit: 24 });
  return { props: { handle, initial } };
};

export default function CategoryPage({
  handle,
  initial,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  // In the browser, through the provider's browser key. The server's answer
  // shows at once; the hook fetches again once it is older than 60 s.
  const { data } = useProducts({ category: handle, limit: 24 }, { initialData: initial });
  return (
    <ul>
      {data?.products.map((product) => (
        <li key={product.handle}>{product.title}</li>
      ))}
    </ul>
  );
}