From bigcommerce-commerce
Provides Next.js App Router patterns for BigCommerce headless storefronts: Server/Client Components, data fetching with ISR/GraphQL, middleware, API routes, Catalyst.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin bigcommerce-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
https://nextjs.org/docs for Next.js documentationhttps://www.catalyst.dev/ for Catalyst-specific patternsnextjs app router data fetching patterns for current best practicesapp/
├── 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
| 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) |
await async operations directlyMark with 'use client' directive:
useState, useEffect, etc.)// 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>;
}
async function ProductsPage() {
const products = await fetch(`${STORE_URL}/graphql`, {
method: 'POST',
headers: { Authorization: `Bearer ${STOREFRONT_TOKEN}` },
body: JSON.stringify({ query: PRODUCTS_QUERY }),
next: { revalidate: 300 }, // ISR: revalidate every 5 minutes
}).then(r => r.json());
return <ProductGrid products={products.data.site.products} />;
}
| Strategy | Use Case | Config |
|---|---|---|
| Static | Rarely changing data | { cache: 'force-cache' } |
| ISR | Product/category pages | { next: { revalidate: 300 } } |
| Dynamic | Cart, checkout, account | { cache: 'no-store' } |
| On-Demand | After webhook events | revalidateTag('products') |
Trigger revalidation from webhooks:
// app/api/webhooks/route.ts
export async function POST(request: Request) {
const body = await request.json();
if (body.scope === 'store/product/updated') {
revalidateTag('products');
}
return Response.json({ revalidated: true });
}
// app/api/webhooks/orders/route.ts
export async function POST(request: Request) {
const body = await request.json();
// Verify webhook authenticity
// Process order event
return Response.json({ received: true });
}
Proxy BigCommerce API calls to hide credentials:
// app/api/products/route.ts
export async function GET() {
const response = await fetch(`${BC_API_URL}/v3/catalog/products`, {
headers: { 'X-Auth-Token': process.env.BC_ACCESS_TOKEN! },
});
const data = await response.json();
return Response.json(data);
}
// middleware.ts
export function middleware(request: NextRequest) {
const token = request.cookies.get('auth_token');
if (request.nextUrl.pathname.startsWith('/account') && !token) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
Route users to the correct channel based on locale or region.
import Image from 'next/image';
<Image
src={product.imageUrl}
alt={product.name}
width={500}
height={500}
priority={isAboveFold} // Preload for LCP images
/>
Configure remotePatterns in next.config.js for BigCommerce CDN domains.
# .env.local
BIGCOMMERCE_STORE_HASH=abc123
BIGCOMMERCE_ACCESS_TOKEN=xxx # Server-only (no NEXT_PUBLIC_ prefix)
NEXT_PUBLIC_STORE_URL=https://... # Available in browser
BIGCOMMERCE_STOREFRONT_TOKEN=yyy # Client-side GraphQL
Catalyst includes a typed GraphQL client:
client/queries/ directoryclient/mutations/ directoryCatalyst provides pre-built components:
'use client' only when neededNEXT_PUBLIC_ prefixnext/image for automatic optimizationloading.tsx or Suspenseerror.tsx boundariesFetch the Next.js documentation and Catalyst source for exact API, configuration options, and current patterns before implementing.