sfnext-data-fetching

Data Fetching Skill

This skill covers server-side data fetching patterns in Storefront Next — loaders, actions, and the useScapiFetcher hook.

Overview

Storefront Next mandates server-only data loading. All SCAPI requests execute on the MRT server, never in the browser. Three mechanisms exist:

Mechanism	When It Runs	Use Case
loader	Route navigation	Initial page data
action	Form submission	Mutations (add to cart, update profile)
useScapiFetcher	User interaction	On-demand fetching (search suggestions, infinite scroll)

Loader Patterns

Loaders can be synchronous (returning promises for streaming) or async (awaiting critical data). Choose based on what the page needs:

• Sync loader — Returns promises directly. Enables streaming SSR: the shell renders immediately while data streams in. Best when all data can render progressively.
• Async loader — Awaits critical data before rendering. Use when data is required for SEO or the page shell (e.g., category name in breadcrumbs). Non-critical data can still be returned as promises for streaming.

// Sync — full streaming (all data renders progressively)
export function loader({ params, context }: LoaderFunctionArgs): ProductPageData {
    const clients = createApiClients(context);
    return {
        product: clients.shopperProducts.getProduct({
            params: { path: { id: params.productId } }
        }).then(({ data }) => data),
        reviews: clients.shopperProducts.getReviews({
            params: { path: { id: params.productId } }
        }).then(({ data }) => data),
    };
}

// Async — await critical data, stream the rest (mixed strategy)
export async function loader({ params, context }: LoaderFunctionArgs): Promise<CategoryPageData> {
    const clients = createApiClients(context);

    // Await critical data needed for page shell/SEO
    const category = await clients.shopperProducts.getCategory({
        params: { path: { id: params.categoryId } }
    }).then(({ data }) => data);

    return {
        category,  // Resolved immediately
        products: clients.shopperSearch.productSearch({
            params: { query: { q: '', refine: { cgid: params.categoryId } } }
        }).then(({ data }) => data),  // Streamed
    };
}

When to Use Each Pattern

Pattern	When	Example
Sync (full streaming)	All data can render progressively	Product page with reviews
Async (await critical)	SEO-critical data needed for page shell	Category page (needs category name)
Mixed	Some data critical, some deferrable	Category name (await) + product grid (stream)

See Loader Patterns Reference for more patterns and data flow diagrams.

Action Functions

Handle mutations (form submissions, cart updates):

import { data, redirect } from 'react-router';

export async function action({ request, context }: ActionFunctionArgs) {
    const formData = await request.formData();
    const productId = formData.get('productId') as string;

    const clients = createApiClients(context);

    try {
        await clients.shopperBasketsV2.addItemToBasket({
            params: {
                path: { basketId },
                body: { productId, quantity: 1 },
            },
        });
        return data({ success: true });
    } catch (error) {
        return data({ success: false, error: error.message }, { status: 400 });
    }
}

useScapiFetcher — Interactive Data Fetching

For on-demand data fetching triggered by user interactions (after page load):

import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';

export function useSearchSuggestions({ q, limit, currency }) {
    const parameters = useMemo(
        () => ({ params: { query: { q, limit, currency } } }),
        [q, limit, currency]
    );

    const fetcher = useScapiFetcher(
        'shopperSearch',
        'getSearchSuggestions',
        parameters
    );

    const refetch = useCallback(async () => {
        await fetcher.load();
    }, [fetcher]);

    return {
        data: fetcher.data,
        isLoading: fetcher.state === 'loading',
        refetch,
    };
}

See SCAPI Fetcher Reference for the complete useScapiFetcher API.

API Client Usage

Always use createApiClients(context) in loaders and actions:

import { createApiClients } from '@/lib/api-clients';

export function loader({ context }: LoaderFunctionArgs) {
    const clients = createApiClients(context);

    clients.shopperProducts.getProduct({...});
    clients.shopperCustomers.getCustomer({...});
    clients.shopperBasketsV2.getBasket({...});
    clients.shopperSearch.productSearch({...});
    clients.shopperOrders.getOrder({...});
}

Parallel vs Sequential Requests

// GOOD — Parallel requests (all start simultaneously)
export function loader({ context }: LoaderFunctionArgs) {
    const clients = createApiClients(context);
    return {
        product: clients.shopperProducts.getProduct({...}).then(({ data }) => data),
        reviews: clients.shopperProducts.getReviews({...}).then(({ data }) => data),
        recommendations: clients.shopperProducts.getRecommendations({...}).then(({ data }) => data),
    };
}

// AVOID — Sequential awaits of independent requests (unnecessarily slow)
export async function loader({ context }: LoaderFunctionArgs) {
    const clients = createApiClients(context);
    const product = await clients.shopperProducts.getProduct({...});  // Waits...
    const reviews = await clients.shopperProducts.getReviews({...});  // Then waits again
    return { product, reviews };
}

Common Pitfalls

Pitfall	Problem	Solution
Awaiting all data	Blocks page transition unnecessarily	Only await SEO-critical data; stream the rest
Client loaders	Not permitted in Storefront Next	Use server loader or useScapiFetcher
Sequential await	Slow data loading	Return promises in parallel
Missing context in getConfig()	Config unavailable	Pass context in server loaders: getConfig(context)

Related Skills

• storefront-next:sfnext-scapi-management - Adding/removing SCAPI clients and discovering API shapes
• storefront-next:sfnext-custom-apis - Calling custom API endpoints from loaders/actions
• storefront-next:sfnext-routing - Route file conventions and module exports
• storefront-next:sfnext-components - Rendering loader data with createPage and Suspense
• storefront-next:sfnext-state-management - Client-side Zustand stores (NOT data fetching)
• storefront-next:sfnext-authentication - Auth context in loaders

Reference Documentation

• Loader Patterns Reference - Data flow diagrams and advanced patterns
• SCAPI Fetcher Reference - Complete useScapiFetcher API and examples