Headless Shopify на Next.js: повний гайд з архітектури (2026)

Headless Shopify на Next.js - де-факто стандарт для високопродуктивного eCommerce у 2026 році. Це не спрощення порівняно з Liquid-темами - це переробка трьох рівнів, які більшість туторіалів обходять: API-поверхні Shopify - всі три рівні (Storefront API, Admin API, Customer Account API) з їхніми моделями автентифікації, rate limiting та пагінацією; data layer Next.js App Router - як RSC, Data Cache і generateStaticParams прибирають клієнтські waterfalls для каталогу; і моделі state-меж - що йде у Server Components, що потребує 'use client', та точні механізми (cookies для cart ID, OAuth PKCE, оптимістичні оновлення) інтерактивного шару. Все базується на реальних продакшн-реалізаціях, включаючи Shopify Plus з кількома сторами.

Частина I - API-поверхня Shopify: три рівні, три різних контракти

• Storefront API (GraphQL, публічний): Ендпоінт https://{shop}.myshopify.com/api/{version}/graphql.json. Автентифікація через X-Shopify-Storefront-Access-Token. Rate limiting cost-based: 1,000 cost units/запит, refill 500 units/секунду. Пагінація - лише cursor-based. API версіонований (квартальні релізи). Версія має бути явно зафіксована - ніколи не використовуйте unstable у продакшні.
• Admin API (приватний): Повне управління магазином. Автентифікація через X-Shopify-Access-Token. Ніколи не розкривайте Admin API credentials браузеру. Лише Route Handlers або серверні утиліти з import 'server-only'.
• Customer Account API (OAuth 2.0, 2024+): Shopify відмовився від legacy Storefront API мутацій клієнтів у 2024. Заміна - Customer Account API: окремий OAuth 2.0 сервіс на shopify.com/authentication/{shop-id}. Використовує PKCE flow (RFC 7636), видає short-lived access tokens (1 година) + refresh tokens. Будь-яка нова headless-реалізація у 2026 обов'язково використовує цей API.

Частина II - Data Layer: типізований GraphQL з кодогенерацією

• Інструментарій: @graphql-codegen/cli + @graphql-codegen/typescript-operations + @shopify/api-codegen-preset. Пресет завантажує схему Storefront API для зафіксованої версії та генерує TypeScript-типи для всіх .graphql-операцій. Запускати у CI.
• Стратегія фрагментів: Перевикористовувані фрагменти для форм даних компонентів. Запити PDP та PLP складаються з фрагментів - без розбіжності форм даних між сторінками.
• Серверний data layer: Всі Shopify-функції у lib/shopify/ з import 'server-only'. TypeScript видасть помилку збірки при спробі імпортувати серверний код у Client Component.

Частина III - Архітектура каталогу: generateStaticParams та ISR

• PDP generateStaticParams: getAllProductHandles() пагінує Storefront API cursor-based при збірці. 5,000 продуктів = 20 запитів при збірці, нуль запитів при обслуговуванні сторінки з CDN.
• ISR конфігурація: export const revalidate = 3600; - регенерація у фоні щогодини. On-demand через вебхук Shopify → Route Handler → revalidateTag('product-' + handle).
• RSC-патерн для PDP: Сторінка - async Server Component. Заголовок, опис, зображення, характеристики = Server Components, нуль байт у клієнтський бандл. <AddToCartButton> та <VariantSelector> - єдині 'use client' компоненти.

Частина IV - Стан кошика: cookie-сховище та оптимістичні оновлення

• Cart API (поточний стандарт): Мутації: cartCreate, cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartBuyerIdentityUpdate.
• Cookie-сховище cart ID: localStorage недоступний у Server Components. cart.id зберігати у cookie: httpOnly: false, sameSite: 'lax', path: '/', maxAge: 30 * 24 * 60 * 60. У Server Component читається через cookies() для рендерингу кількості товарів у шапці.
• Межа `'use client'`: <CartProvider> - Client Component з React Context. Мутації кошика проксуються через Route Handlers - токен Storefront API ніколи не потрапляє в браузер.
• Оптимістичні оновлення (React 19): useOptimistic - миттєвий UI-відгук до підтвердження від сервера. При помилці мутації React автоматично повертає серверний стан.

Частина V - Автентифікація: OAuth PKCE через Customer Account API

• PKCE flow (RFC 7636): (1) Генерація code_verifier. (2) Обчислення code_challenge = BASE64URL(SHA-256(code_verifier)). (3) Редирект на shopify.com/authentication/{shop-id}/oauth/authorize. (4) Обмін code + code_verifier на access token у Route Handler. code_verifier зберігається в httpOnly cookie.
• Auth.js v5 adapter: Customer Account API конфігурується як custom provider. Auth.js управляє оновленням токена, серіалізацією сесії та життєвим циклом PKCE verifier.
• `cartBuyerIdentityUpdate` після логіну: Пов'язує анонімний кошик гостя з акаунтом клієнта - відкриває історію замовлень, збережені адреси, нарахування балів лояльності.

Частина VI - SEO та продуктивність

• Product structured data: Schema Product з Offer (ціна, валюта, доступність), AggregateRating, BreadcrumbList. Product.url - завжди canonical URL без ?variant=.
• Канонікал URL варіантів: У generateMetadata() завжди повертати alternates: { canonical: '/products/' + handle } без параметра варіанта. Консолідує всі PageRank-сигнали на базовий URL продукту.
• `'use client'` поверхня на PDP: Лише <VariantSelector> + <AddToCartButton> (~15–25 KB gzip). Решта - Server Components. Підсумковий бандл: 80–120 KB gzip. Детальний аналіз впливу на INP - в The Universal Web Performance Architecture.
• Shopify CDN трансформації: ?width=800&format=avif&quality=80 - вбудована трансформація, окремий CDN не потрібен. Preconnect до cdn.shopify.com усуває ~150–200ms затримки DNS+TLS.

Частина VII - Продакшн-патерни та кейси

• Global Home & Decor eCommerce ([кейси](/uk/projects)): Multi-storefront Shopify Plus + Magento 2 для B2B і B2C на 12 ринках. Єдиний типізований інтерфейс Product для обох бекендів. Патерн composable headless architecture у найбільш вимогливій формі.
• High-Load Retail (Traffic Spikes): generateStaticParams пре-рендерить весь каталог при збірці - пікові навантаження поглинаються CDN edge без origin-запитів до Shopify API. Для поглиблених патернів enterprise eCommerce - сервіс enterprise ecommerce.
• Shopify Hydrogen vs. Next.js: Hydrogen - при єдиному бекенді Shopify та знайомстві команди з Remix. Next.js - при кількох бекендах або існуючій кодовій базі Next.js. Повне порівняння - Shopify Hydrogen vs Next.js Commerce.

FAQ

• Чому не можна зберігати ID кошика в localStorage? localStorage недоступний у Server Components. Кількість товарів у шапці має рендеритися на сервері. Cookie з httpOnly: false та sameSite: 'lax' - єдиний механізм, доступний і серверу (cookies()), і клієнту.
• Як обробляти rate limiting Storefront API при великому каталозі? Патерн ISR означає нуль Storefront API-викликів для закешованих сторінок. Rate limiting актуальний лише при збірці та ISR-регенерації - обидва випадки мають низьку частоту.
• Як реалізувати on-demand ISR при оновленні продукту в Shopify? Вебхук Shopify products/update → Route Handler з валідацією HMAC-підпису → revalidateTag('product-' + handle).
• Як правильно обробляти `?variant=` URL для SEO? У generateMetadata() завжди повертати alternates: { canonical: '/products/' + handle } без параметра варіанта. Ніколи не включати ?variant= URL у sitemap.

Джерела

• Shopify. 'Storefront API Reference': https://shopify.dev/docs/api/storefront
• Shopify. 'Customer Account API': https://shopify.dev/docs/api/customer
• Shopify. 'Shopify API Rate Limits': https://shopify.dev/docs/api/usage/rate-limits
• RFC 7636. 'Proof Key for Code Exchange': https://datatracker.ietf.org/doc/html/rfc7636
• Next.js Team. 'generateStaticParams': https://nextjs.org/docs/app/api-reference/functions/generate-static-params
• Next.js Team. 'Incremental Static Regeneration': https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration
• GraphQL Code Generator. 'TypeScript Operations': https://the-guild.dev/graphql/codegen/plugins/typescript/typescript-operations
• Auth.js. 'Custom OAuth Providers': https://authjs.dev/guides/configuring-oauth-providers
• HTTP Archive. 'Web Almanac 2025 - eCommerce': https://almanac.httparchive.org