sfnext-performance

Storefront Next Performance

Performance rules are part of AGENTS.md ("Performance & Data Rules") and detailed in docs/README-PERFORMANCE.md, docs/README-SUSPENSE.md, docs/README-IMAGES.md and docs/README-PERFORMANCE-METRICS.md in your project. This skill is the working summary plus a checklist to run on your own diff: PERFORMANCE-REVIEW-CHECKLIST.md.

Core rules

1. Server-load data. Await only what SEO, LCP, layout or the HTTP status needs; return promises for the rest (see storefront-next:sfnext-data-fetching).
2. One <Suspense> per async operation, with a skeleton that reserves the final size. No fallback={null} above the fold unless space is reserved.
3. Promise identity must be stable across renders: compose in the loader, read from loaderData/props, never Promise.all/.then/new Promise in render, never useMemo around a promise. Escape hatches: useState(() => ...) pinning or useRef re-pinning.
4. Every use()/<Await> consumer needs a <Suspense> ancestor; otherwise it blocks the first byte of the streamed shell.
5. Heavy or hidden UI (modals, drawers, dialogs, rich editors) is React.lazy and mounted only while needed.
6. Shape data in the loader, not in render.
7. Hints and third-party scripts cost: preconnect only to origins used on every page; load scripts async/defer.

Lazy modals and drawers

import { lazy, Suspense, useState } from 'react';
import { useDeferredUnmount } from '@/hooks/use-deferred-unmount';

const SizeGuide = lazy(() => import('@/components/size-guide').then((m) => ({ default: m.SizeGuide })));

export function SizeGuideButton() {
    const [open, setOpen] = useState(false);
    const mounted = useDeferredUnmount(open); // stays mounted briefly after close for the exit animation
    return (
        <>
            <button onClick={() => setOpen(true)}>Size guide</button>
            {mounted && (
                <Suspense fallback={null}>
                    <SizeGuide open={open} onOpenChange={setOpen} />
                </Suspense>
            )}
        </>
    );
}