nextjs-patterns

Next.js Patterns for BigCommerce

Before writing code

Fetch live docs:

1. Fetch https://nextjs.org/docs for Next.js documentation
2. Fetch https://www.catalyst.dev/ for Catalyst-specific patterns
3. Web-search nextjs app router data fetching patterns for current best practices

App Router Fundamentals

File-Based Routing

app/
├── page.tsx                   # /
├── layout.tsx                 # Root layout
├── products/
│   ├── page.tsx               # /products
│   └── [slug]/
│       └── page.tsx           # /products/:slug
├── cart/
│   └── page.tsx               # /cart
├── api/
│   └── webhooks/
│       └── route.ts           # /api/webhooks (API route)
└── not-found.tsx              # 404 page

Special Files

File	Purpose
page.tsx	Route component
layout.tsx	Shared layout (persists across navigation)
loading.tsx	Loading UI (Suspense boundary)
error.tsx	Error boundary
not-found.tsx	404 page
route.ts	API route handler
template.tsx	Re-rendered layout (no persistence)

Server vs Client Components

Server Components (Default)

• Run on the server only — no JS sent to client
• Can await async operations directly
• Access server-only resources (DB, API tokens, env vars)
• Cannot use hooks, browser APIs, or event handlers

Client Components

Mark with 'use client' directive:

• Run in the browser
• Use React hooks (useState, useEffect, etc.)
• Handle user interactions (onClick, onChange)
• Access browser APIs

Pattern for BigCommerce

// Server Component — fetches data
async function ProductPage({ params }: { params: { slug: string } }) {
  const product = await getProduct(params.slug); // Server-side fetch
  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} /> {/* Client component */}
    </div>
  );
}

// Client Component — handles interactivity
'use client';
function AddToCartButton({ productId }: { productId: number }) {
  const [loading, setLoading] = useState(false);
  const handleClick = async () => { /* add to cart */ };
  return <button onClick={handleClick}>Add to Cart</button>;
}