sfnext-data-fetching

Storefront Next Data Fetching

All data comes from the server. Loaders and actions run on the server with the shopper's session; the browser never calls SCAPI directly. Your project ships docs/README-DATA.md, docs/README-SUSPENSE.md, docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md and docs/README-SHOPPER-CONTEXT.md, plus the "Performance & Data Rules" in AGENTS.md; this skill is the quick path, those are authoritative.

The rules (same as AGENTS.md)

1. Fetch on the server in loader (reads) and action (writes). There is no clientLoader or clientAction.
2. Classify every piece of data:
   • Critical (needed for SEO, LCP, layout stability or the HTTP status): await it in the loader.
   • Non-critical (below the fold, recommendations, reviews, secondary panels): start the request, do not await it, and return the unresolved promise so it streams.
   • Interaction-driven (only after a click, hover or input): fetch on demand with a fetcher.
3. Never block a loader on non-critical data.
4. Pass the promise through loaderData and read it under its own <Suspense> with use() or <Await>. Keep the promise identity stable (compose it in the loader, never Promise.all or .then in render).
5. Export shouldRevalidate on routes whose loaders depend on URL filters (see storefront-next:sfnext-revalidation).

Loader with critical and streamed data

import { Suspense } from 'react';
import { Await } from 'react-router';
import type { Route } from './+types/_app.example';
import { createApiClients } from '@/lib/api-clients.server';
import { fetchProductById } from '@/lib/api/products.server';
import { NormalizedApiError } from '@/lib/api/normalized-api-error';

export async function loader({ context, params }: Route.LoaderArgs) {
    const clients = createApiClients(context);

    // Non-critical: start now, do not await.
    const related = clients.shopperSearch
        .productSearch({ params: { query: { q: 'shirt', limit: 8 } } })
        .then(({ data }) => data.hits ?? []);

    // Critical: needed for status, SEO and LCP.
    try {
        const product = await fetchProductById(context, params.id ?? '', { expand: ['images', 'prices'] });
        if (!product) throw new Response('Not found', { status: 404 });
        return { product, related };
    } catch (e) {
        if (e instanceof NormalizedApiError && e.status) throw new Response(e.message, { status: e.status });
        throw e;
    }
}

export default function Example({ loaderData }: Route.ComponentProps) {
    return (
        <>
            <h1>{loaderData.product.name}</h1>
            <Suspense fallback={<div className="h-40" aria-busy="true" />}>
                <Await resolve={loaderData.related}>{(hits) => <ul>{hits.map((h) => <li key={h.productId}>{h.productName}</li>)}</ul>}</Await>
            </Suspense>
        </>
    );
}