Sfnext Components

Components Skill

This skill covers component development patterns in Storefront Next — createPage HOC, Suspense boundaries, shadcn/ui integration, and Tailwind CSS styling.

Page Component Pattern

Most routes export a default function component that receives loaderData as props:

import { Suspense } from 'react';
import { Await } from 'react-router';
import { SeoMeta } from '@/components/seo-meta';

type ProductPageData = {
    product: Promise;
    reviews: Promise;
};

export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
    return (
        <>
            
            }>
                
                    {(product) => }
                
            
            }>
                
                    {(reviews) => }
                
            
        
    );
}

createPage HOC (Optional)

For pages needing standardized Suspense wrappers and page key management:

import { createPage } from '@/components/create-page';

export default createPage({
    component: ProductView,
    fallback: ,
});

Suspense Boundaries and Code Splitting

Use ` + for streaming loader data, and lazy()` for code-splitting heavy components:

import { lazy, Suspense } from 'react';

// Code-split a heavy component
const CustomerReviewsSection = lazy(() =>
    import('@/components/customer-reviews-section/customer-reviews-section')
);

export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
    return (
        <>
            {/* Stream loader data */}
            }>
                
                    {(product) => }
                
            

            {/* Code-split component */}
            }>
                
            
        
    );
}

shadcn/ui Components

shadcn/ui provides pre-built accessible components. Add them via CLI:

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add dialog

Rules:

• Add components via CLI only (do not manually create files in src/components/ui/)
• src/components/ui/ components are copied into your project and can be customized directly
• Keep app/domain components outside src/components/ui/:

// Optional wrapper for app-specific styling
import { Button } from '@/components/ui/button';

export function PrimaryButton(props: React.ComponentProps) {
    return ;
}

Tailwind CSS Styling

Tailwind CSS v4 is the only permitted styling approach:

import { cn } from '@/lib/utils';

export function ProductCard({ featured }: { featured?: boolean }) {
    return (
        
            
                Product Name
            
        
    );
}

Rules:

• Use Tailwind utility classes as the primary styling approach
• Use cn() for conditional class merging
• Follow mobile-first responsive design (md:, lg: breakpoints)
• Prefer Tailwind over inline styles; inline styles are acceptable for truly dynamic values (e.g., backgroundColor from API data)
• No CSS modules or separate CSS files
• Custom global CSS only in src/app.css

Dark Mode

Theme variables automatically adapt via CSS variables:

    Click me

Responsive Design

    {products.map(p => )}

File Organization

src/components/product-tile/
├── index.tsx              # Component implementation
├── index.test.tsx         # Vitest unit tests
└── stories/
    ├── index.stories.tsx  # Storybook stories
    └── __snapshots__/     # Storybook snapshots (optional)

src/components/product-skeleton/
├── index.tsx              # Skeleton component (separate from main)
├── index.test.tsx
└── stories/
    └── index.stories.tsx

Best Practices

1. Export default function components — Receive loaderData as props
2. Granular Suspense boundaries — Show content progressively as data resolves
3. Use lazy() for heavy components — Code-split below-the-fold or conditional UI
4. Reusable skeleton components — Consistent loading states
5. Colocate tests and stories — Keep test files next to source files
6. TypeScript interfaces — Define proper types for all props

Related Skills

• storefront-next:sfnext-data-fetching - Loader patterns that feed data to components
• storefront-next:sfnext-testing - Writing Vitest tests and Storybook stories
• storefront-next:sfnext-page-designer - Page Designer component integration
• storefront-next:sfnext-i18n - Translating component text

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SalesforceCommerceCloud
• Source: SalesforceCommerceCloud/b2c-developer-tooling
• License: Apache-2.0
• Homepage: https://salesforcecommercecloud.github.io/b2c-developer-tooling/

Install and usage instructions live in the source repository linked above.