orcaqubits/nextjs-react

Next.js & React for Saleor

Before writing code

Fetch live docs:

1. Web-search site:nextjs.org docs app for current Next.js App Router documentation
2. Web-search site:docs.saleor.io storefront for Saleor storefront development guide
3. Web-search site:github.com saleor storefront for the official Saleor storefront template source
4. Web-search site:github.com saleor macaw-ui for MacawUI component library reference
5. Web-search saleor app template Next.js saleor-app-sdk for App development patterns
6. Fetch https://docs.saleor.io/docs/developer/app-store/apps/overview for App architecture

Next.js App Router Conventions

File Conventions

| File | Purpose | Rendering | |------|---------|-----------| | layout.tsx | Shared layout wrapping child routes | Server component (default) | | page.tsx | Unique UI for a route segment | Server component (default) | | loading.tsx | Loading UI (React Suspense) | Server component | | error.tsx | Error boundary for route segment | Client component (required) | | not-found.tsx | 404 UI for route segment | Server component | | template.tsx | Re-rendered layout (no state persistence) | Server component | | route.ts | API route handler | Server-only |

Routing Patterns for Saleor Storefronts

| Route | Segment | Purpose | |-------|---------|---------| | /[channel] | Dynamic channel | Multi-channel routing | | /[channel]/products | Product listing | Category/collection pages | | /[channel]/products/[slug] | Product detail | Single product page | | /[channel]/cart | Cart | Shopping cart | | /[channel]/checkout | Checkout | Checkout flow | | /[channel]/account | Account | Customer dashboard | | /[channel]/search | Search | Product search results |

• Use dynamic segments [channel] for multi-channel support
• Use route groups (storefront) and (dashboard) to organize layouts

Server vs Client Components

Decision Matrix

| Criterion | Server Component | Client Component | |-----------|-----------------|-----------------| | Data fetching | Fetch directly (no waterfall) | Use useQuery hooks | | SEO critical | Yes (HTML in response) | No (client-rendered) | | Interactivity | None (static output) | Click, input, state | | Hooks | Cannot use hooks | useState, useEffect, etc. | | Bundle size | Zero JS sent to client | Included in JS bundle |

Component Patterns for Saleor

| Component | Type | Reason | |-----------|------|--------| | Product list page | Server | SEO, data fetching | | Product detail page | Server | SEO, data fetching | | Add to cart button | Client | Interactivity, state | | Cart sidebar | Client | State management, animation | | Checkout form | Client | Form state, validation | | Search bar | Client | Input handling, debounce | | Navigation | Server | Static, SEO links | | Price display | Server | Channel-aware, static |

• Default to server components — add "use client" only when needed; pass server-fetched data as props to client components

GraphQL Client Integration

urql (Saleor Recommended)

| Package | Purpose | |---------|---------| | @urql/core | Core urql client | | @urql/next | Next.js App Router integration | | graphql | GraphQL parsing (peer dependency) |

Setup Pattern

| Concern | Implementation | |---------|---------------| | Server client | Create urql client in server utility, use in server components | | Client provider | Wrap client components with UrqlProvider in layout | | Auth header | Add Authorization: Bearer <token> via fetchOptions | | Channel header | Add saleor-channel: <slug> via fetchOptions | | SSR | Use @urql/next for SSR data hydration |

Apollo Client Alternative

• Use @apollo/client with @apollo/experimental-nextjs-app-support
• Provides normalized caching (useful for complex state)
• Heavier bundle than urql

Data Fetching Patterns

| Pattern | Where | How | |---------|-------|-----| | Server component fetch | page.tsx, layout.tsx | await client.query() directly | | Client query hook | "use client" components | useQuery(Document, { variables }) | | Server action | Form submissions | "use server" functions calling GraphQL | | Route handler | route.ts | API endpoint calling Saleor GraphQL | | Parallel fetching | Server component | Promise.all([query1, query2]) |

• Fetch data as high in the component tree as possible
• Use Promise.all for parallel independent queries
• Use server actions for mutations (checkout updates, cart modifications)

Caching Strategies

| Strategy | Scope | Configuration | |----------|-------|---------------| | Static | Build time | export const revalidate = false | | ISR | Time-based revalidation | export const revalidate = 60 (seconds) | | On-demand | Webhook-triggered | revalidatePath() or revalidateTag() | | No cache | Always fresh | export const dynamic = "force-dynamic" |

Saleor Caching Recommendations

| Page | Strategy | Rationale | |------|----------|-----------| | Product listing | ISR (60s) | Content changes infrequently | | Product detail | ISR (60s) + on-demand | Revalidate on product webhook | | Cart / Checkout | No cache | User-specific, transactional | | Static pages | Static | CMS content, rarely changes |

Environment Variables

| Variable | Where | Purpose | |----------|-------|---------| | NEXT_PUBLIC_SALEOR_API_URL | Client + Server | Saleor GraphQL endpoint | | SALEOR_API_URL | Server only | Server-side GraphQL endpoint | | NEXT_PUBLIC_DEFAULT_CHANNEL | Client + Server | Default channel slug | | SALEOR_APP_TOKEN | Server only | App token for authenticated queries |

• Prefix with NEXT_PUBLIC_ for client-accessible variables
• Keep secrets (App tokens, API keys) server-only (no prefix)

Tailwind CSS Setup

| Step | Action | |------|--------| | Install | npm install -D tailwindcss @tailwindcss/postcss postcss | | Configure | Add @tailwindcss/postcss to postcss.config.js | | Content paths | Set content in tailwind.config.ts to include all component files | | Global import | Add @import "tailwindcss" to globals.css |

• The official Saleor storefront template uses Tailwind CSS
• Use CSS custom properties for theme tokens (channel-specific branding)

MacawUI Integration for Apps

MacawUI is the Saleor Dashboard component library used in Saleor Apps:

| Component Category | Examples | |-------------------|----------| | Layout | Box, Layout, Sidebar | | Forms | Input, Select, Checkbox, Multiselect | | Data display | List, Table, Chip, Tag | | Feedback | Alert, Banner, Skeleton | | Actions | Button, IconButton, Dropdown |

| Context | UI Library | Reason | |---------|-----------|--------| | Saleor App (Dashboard iframe) | MacawUI | Consistent Dashboard look and feel | | Storefront | Tailwind CSS / custom | Brand-specific design |

• Install via npm install @saleor/macaw-ui
• Wrap App root with <ThemeProvider> from MacawUI
• MacawUI follows the Saleor design system (spacing, colors, typography)

Image Optimization

| Feature | Configuration | |---------|---------------| | next/image | Use for all product and media images | | Remote patterns | Add Saleor media domain to next.config.js images.remotePatterns | | Sizes | Set sizes attribute for responsive images | | Priority | Add priority to above-the-fold images (hero, first product) | | Formats | Next.js auto-serves WebP/AVIF when supported |

Best Practices

• Default to server components and add "use client" only for interactivity
• Fetch data in server components and pass as props to client components
• Use the App Router file conventions (page.tsx, layout.tsx, error.tsx) consistently
• Set up GraphQL code generation for type-safe queries and mutations
• Use ISR with on-demand revalidation for product pages (webhook-triggered)
• Include saleor-channel header in all GraphQL client configurations
• Use MacawUI for Dashboard App UI and Tailwind CSS for storefronts
• Optimize images with next/image and configure remote patterns for Saleor media
• Keep environment variables separated between server-only and client-accessible

Fetch the Next.js and Saleor storefront documentation for current App Router patterns, GraphQL client setup, and component conventions before implementing.