1---2name: nextjs-react3description: Build Next.js and React applications for Saleor — App Router, server and client components, GraphQL client integration, MacawUI in Apps, and Tailwind CSS. Use when building Saleor storefronts or Apps with Next.js.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/nextjs-react7---89# Next.js & React for Saleor1011## Before writing code1213**Fetch live docs**:141. Web-search `site:nextjs.org docs app` for current Next.js App Router documentation152. Web-search `site:docs.saleor.io storefront` for Saleor storefront development guide163. Web-search `site:github.com saleor storefront` for the official Saleor storefront template source174. Web-search `site:github.com saleor macaw-ui` for MacawUI component library reference185. Web-search `saleor app template Next.js saleor-app-sdk` for App development patterns196. Fetch `https://docs.saleor.io/docs/developer/app-store/apps/overview` for App architecture2021## Next.js App Router Conventions2223### File Conventions2425| File | Purpose | Rendering |26|------|---------|-----------|27| `layout.tsx` | Shared layout wrapping child routes | Server component (default) |28| `page.tsx` | Unique UI for a route segment | Server component (default) |29| `loading.tsx` | Loading UI (React Suspense) | Server component |30| `error.tsx` | Error boundary for route segment | Client component (required) |31| `not-found.tsx` | 404 UI for route segment | Server component |32| `template.tsx` | Re-rendered layout (no state persistence) | Server component |33| `route.ts` | API route handler | Server-only |3435### Routing Patterns for Saleor Storefronts3637| Route | Segment | Purpose |38|-------|---------|---------|39| `/[channel]` | Dynamic channel | Multi-channel routing |40| `/[channel]/products` | Product listing | Category/collection pages |41| `/[channel]/products/[slug]` | Product detail | Single product page |42| `/[channel]/cart` | Cart | Shopping cart |43| `/[channel]/checkout` | Checkout | Checkout flow |44| `/[channel]/account` | Account | Customer dashboard |45| `/[channel]/search` | Search | Product search results |4647- Use dynamic segments `[channel]` for multi-channel support48- Use route groups `(storefront)` and `(dashboard)` to organize layouts4950## Server vs Client Components5152### Decision Matrix5354| Criterion | Server Component | Client Component |55|-----------|-----------------|-----------------|56| **Data fetching** | Fetch directly (no waterfall) | Use `useQuery` hooks |57| **SEO critical** | Yes (HTML in response) | No (client-rendered) |58| **Interactivity** | None (static output) | Click, input, state |59| **Hooks** | Cannot use hooks | `useState`, `useEffect`, etc. |60| **Bundle size** | Zero JS sent to client | Included in JS bundle |6162### Component Patterns for Saleor6364| Component | Type | Reason |65|-----------|------|--------|66| **Product list page** | Server | SEO, data fetching |67| **Product detail page** | Server | SEO, data fetching |68| **Add to cart button** | Client | Interactivity, state |69| **Cart sidebar** | Client | State management, animation |70| **Checkout form** | Client | Form state, validation |71| **Search bar** | Client | Input handling, debounce |72| **Navigation** | Server | Static, SEO links |73| **Price display** | Server | Channel-aware, static |7475- Default to server components — add `"use client"` only when needed; pass server-fetched data as props to client components7677## GraphQL Client Integration7879### urql (Saleor Recommended)8081| Package | Purpose |82|---------|---------|83| `@urql/core` | Core urql client |84| `@urql/next` | Next.js App Router integration |85| `graphql` | GraphQL parsing (peer dependency) |8687### Setup Pattern8889| Concern | Implementation |90|---------|---------------|91| **Server client** | Create urql client in server utility, use in server components |92| **Client provider** | Wrap client components with `UrqlProvider` in layout |93| **Auth header** | Add `Authorization: Bearer <token>` via `fetchOptions` |94| **Channel header** | Add `saleor-channel: <slug>` via `fetchOptions` |95| **SSR** | Use `@urql/next` for SSR data hydration |9697### Apollo Client Alternative9899- Use `@apollo/client` with `@apollo/experimental-nextjs-app-support`100- Provides normalized caching (useful for complex state)101- Heavier bundle than urql102103## Data Fetching Patterns104105| Pattern | Where | How |106|---------|-------|-----|107| **Server component fetch** | `page.tsx`, `layout.tsx` | `await client.query()` directly |108| **Client query hook** | `"use client"` components | `useQuery(Document, { variables })` |109| **Server action** | Form submissions | `"use server"` functions calling GraphQL |110| **Route handler** | `route.ts` | API endpoint calling Saleor GraphQL |111| **Parallel fetching** | Server component | `Promise.all([query1, query2])` |112113- Fetch data as high in the component tree as possible114- Use `Promise.all` for parallel independent queries115- Use server actions for mutations (checkout updates, cart modifications)116117## Caching Strategies118119| Strategy | Scope | Configuration |120|----------|-------|---------------|121| **Static** | Build time | `export const revalidate = false` |122| **ISR** | Time-based revalidation | `export const revalidate = 60` (seconds) |123| **On-demand** | Webhook-triggered | `revalidatePath()` or `revalidateTag()` |124| **No cache** | Always fresh | `export const dynamic = "force-dynamic"` |125126### Saleor Caching Recommendations127128| Page | Strategy | Rationale |129|------|----------|-----------|130| **Product listing** | ISR (60s) | Content changes infrequently |131| **Product detail** | ISR (60s) + on-demand | Revalidate on product webhook |132| **Cart / Checkout** | No cache | User-specific, transactional |133| **Static pages** | Static | CMS content, rarely changes |134135## Environment Variables136137| Variable | Where | Purpose |138|----------|-------|---------|139| `NEXT_PUBLIC_SALEOR_API_URL` | Client + Server | Saleor GraphQL endpoint |140| `SALEOR_API_URL` | Server only | Server-side GraphQL endpoint |141| `NEXT_PUBLIC_DEFAULT_CHANNEL` | Client + Server | Default channel slug |142| `SALEOR_APP_TOKEN` | Server only | App token for authenticated queries |143144- Prefix with `NEXT_PUBLIC_` for client-accessible variables145- Keep secrets (App tokens, API keys) server-only (no prefix)146147## Tailwind CSS Setup148149| Step | Action |150|------|--------|151| **Install** | `npm install -D tailwindcss @tailwindcss/postcss postcss` |152| **Configure** | Add `@tailwindcss/postcss` to `postcss.config.js` |153| **Content paths** | Set `content` in `tailwind.config.ts` to include all component files |154| **Global import** | Add `@import "tailwindcss"` to `globals.css` |155156- The official Saleor storefront template uses Tailwind CSS157- Use CSS custom properties for theme tokens (channel-specific branding)158159## MacawUI Integration for Apps160161MacawUI is the Saleor Dashboard component library used in Saleor Apps:162163| Component Category | Examples |164|-------------------|----------|165| **Layout** | `Box`, `Layout`, `Sidebar` |166| **Forms** | `Input`, `Select`, `Checkbox`, `Multiselect` |167| **Data display** | `List`, `Table`, `Chip`, `Tag` |168| **Feedback** | `Alert`, `Banner`, `Skeleton` |169| **Actions** | `Button`, `IconButton`, `Dropdown` |170171| Context | UI Library | Reason |172|---------|-----------|--------|173| **Saleor App (Dashboard iframe)** | MacawUI | Consistent Dashboard look and feel |174| **Storefront** | Tailwind CSS / custom | Brand-specific design |175176- Install via `npm install @saleor/macaw-ui`177- Wrap App root with `<ThemeProvider>` from MacawUI178- MacawUI follows the Saleor design system (spacing, colors, typography)179180## Image Optimization181182| Feature | Configuration |183|---------|---------------|184| **next/image** | Use for all product and media images |185| **Remote patterns** | Add Saleor media domain to `next.config.js` `images.remotePatterns` |186| **Sizes** | Set `sizes` attribute for responsive images |187| **Priority** | Add `priority` to above-the-fold images (hero, first product) |188| **Formats** | Next.js auto-serves WebP/AVIF when supported |189190## Best Practices191192- Default to server components and add `"use client"` only for interactivity193- Fetch data in server components and pass as props to client components194- Use the App Router file conventions (`page.tsx`, `layout.tsx`, `error.tsx`) consistently195- Set up GraphQL code generation for type-safe queries and mutations196- Use ISR with on-demand revalidation for product pages (webhook-triggered)197- Include `saleor-channel` header in all GraphQL client configurations198- Use MacawUI for Dashboard App UI and Tailwind CSS for storefronts199- Optimize images with `next/image` and configure remote patterns for Saleor media200- Keep environment variables separated between server-only and client-accessible201202Fetch the Next.js and Saleor storefront documentation for current App Router patterns, GraphQL client setup, and component conventions before implementing.