[fredericoo]

TL;DR: Updates the Next.js template to match the current example pattern for Cache Components, streamed app shell data, and Suspense-backed cart state.

Before

The root layout waited for cart and navigation data before rendering the template shell:

const [{data: cartData}, navResult] = await Promise.all([
  cartHandlers.get({storefrontClient}),
  storefrontClient.graphql(NAV_COLLECTIONS_QUERY),
]);

Cart UI read directly from useCart, so initial cart loading was handled as local loading state rather than a Suspense boundary.

After

The root layout is a static shell. Request-bound cart and navigation setup lives in AppShell, which streams under Suspense:

<Suspense fallback={<AppShellFallback />}>
  <AppShell>{children}</AppShell>
</Suspense>

The cart seed is passed to CartProvider as a promise, and cart surfaces that need resolved cart data use useSuspenseCart().

What this changes

• Enables cacheComponents for the Next.js template.
• Adds an AppShell server component for request-bound cart and nav setup.
• Passes the cart seed promise into CartProvider so the shell can stream.
• Exports and uses useSuspenseCart() for full-cart reads.
• Removes force-dynamic route exports that are not compatible with Cache Components.
• Adds accessible loading fallbacks for the app shell, cart route, and redirect checks.
• Keeps the cart drawer header stable while only the cart body streams.
• Emits cart_viewed once per drawer open cycle instead of on every cart update while open.

UX impact

The storefront shell can render before personalised cart data resolves. Loading states keep main#main-content and status text available so keyboard and assistive tech users do not lose page context during Suspense fallbacks.

Out of scope

• Existing template lint debt in CollectionBrowse.tsx and standard-actions.d.ts.
• Existing @next/next/no-img-element warnings from the template image strategy.

Risk

• Redirect checks now render a neutral "Checking redirect..." fallback before showing the 404 content. This avoids announcing "Not found" before a Shopify redirect lookup completes, but still relies on Next's streamed redirect behaviour under Cache Components.
• Cart drawer analytics now publish once per open cycle. If analytics expected another cart_viewed after each in-drawer cart mutation, this changes that behaviour intentionally.

How to Test

1. From templates/nextjs, run pnpm dev.
2. Open http://localhost:3000.
3. Confirm the homepage renders and the cart count appears after cart data resolves.
4. Open the cart drawer and confirm the header/close button stay stable while cart content loads.
5. Visit /cart and confirm the cart route renders with the same cart state.
6. Visit /collections, a collection page, /search, and a product page to confirm the streamed shell still wraps each route.

[andguy95]

Top hatted template locally, looks to behave accordingly.