Інтеграція Shopify Storefront API з кастомним фронтендом
Стандартна тема Shopify впирається в стелю продуктивності та кастомізації: URL-архітектура жорстко задана (тільки /products/product-handle), чекаут не кастомізувати без підписки Plus, а складні анімації перетворюються на танець з бубном навколо Liquid. У результаті сторінки завантажуються повільно: TTFB може досягати 800 мс, LCP — 4–6 секунд на мобільних пристроях. Коли клієнт просить нестандартний інтерфейс — кастомні сторінки, складні фільтри, PWA, мультимовність — ми переходимо на headless: використовуємо Shopify як headless commerce backend, а фронтенд пишемо на Next.js, Nuxt або Astro. За останні кілька місяців ми реалізували понад десяток таких проєктів — від кастомних вітрин до PWA-додатків з інтеграцією пошуку та персональних рекомендацій.
У цій статті розберемо, як працює Headless commerce на Shopify Storefront API: від автентифікації до кошика та ISR. Ви отримаєте конкретні приклади коду та архітектурні рішення для власного проєкту.
Проблеми, які вирішує headless
Обмеження стандартної теми:
- URL-архітектура негнучка — не можна зробити
/brand/product-name, що шкодить SEO. - Чекаут без Shopify Plus не кастомізувати: поля, кроки, кастомні сценарії недоступні.
- Анімація та UX — Liquid не тягне складну анімацію, React/Next.js справляються легко.
- Об'єднання кількох магазинів — одна вітрина може агрегувати товари з різних Shopify-акаунтів.
- Мобільний додаток використовує той самий API, що й веб, скорочуючи розробку.
Кожна з цих проблем коштує бізнесу часу та грошей. Ми вирішуємо їх за допомогою Storefront API — GraphQL-інтерфейсу, який дає доступ до каталогу, кошика та чекауту. Економія на хостингу за рахунок статики становить до 5000 грн на місяць, а конверсія зростає на 20–30% завдяки швидкості.
Як працює Storefront API: автентифікація
Для доступу потрібен публічний Storefront API access token — створюється в адмінці: Admin > Apps > Develop apps > [App] > Configuration > Storefront API access scopes
Токен передається в заголовку X-Shopify-Storefront-Access-Token. Він публічний, тому вбудовується в JS-код фронтенду — це безпечно, оскільки права обмежені (читання каталогу, мутації кошика).
Наш клієнт на TypeScript виглядає так:
// lib/shopify/client.ts const SHOPIFY_DOMAIN = process.env.SHOPIFY_STORE_DOMAIN!; const STOREFRONT_TOKEN = process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN!; export async function storefrontFetch<T>({ query, variables, cache = 'force-cache', tags, }: { query: string; variables?: Record<string, unknown>; cache?: RequestCache; tags?: string[]; }): Promise<T> { const res = await fetch( `https://${SHOPIFY_DOMAIN}/api/graphql.json`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Shopify-Storefront-Access-Token': STOREFRONT_TOKEN, }, body: JSON.stringify({ query, variables }), cache, next: tags ? { tags } : undefined, } ); if (!res.ok) throw new Error(`Storefront API error: ${res.status}`); const { data, errors } = await res.json(); if (errors?.length) throw new Error(errors[0].message); return data; } Як отримувати каталог товарів через Storefront API?
Типовий запит товарів з метаполями:
// lib/shopify/queries/products.ts const GET_PRODUCTS = ` query getProducts($first: Int!, $after: String, $sortKey: ProductSortKeys, $reverse: Boolean, $query: String) { products(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, query: $query) { edges { cursor node { id handle title availableForSale priceRange { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } featuredImage { url altText width height } variants(first: 1) { edges { node { id availableForSale selectedOptions { name value } } } } metafield(namespace: "custom", key: "badge") { value } } } pageInfo { hasNextPage endCursor } } } `; export async function getProducts({ first = 24, after, sortKey = 'RELEVANCE', reverse = false, query, }: ProductsQueryParams) { const data = await storefrontFetch<{ products: ProductConnection }>({ query: GET_PRODUCTS, variables: { first, after, sortKey, reverse, query }, tags: ['products'], }); return data.products; } Особливості: курсорна пагінація через after, можливість фільтрації через параметр query (синтаксис Shopify Search). Для фасетної фільтрації використовуємо collection.products з фільтрами за ціною, атрибутами та доступністю.
Як керувати кошиком через Cart API?
Сучасний Cart API замінює застарілий Checkout API. Кошик зберігається на стороні Shopify, ID зберігаємо в cookie або localStorage.
// lib/shopify/queries/cart.ts const CREATE_CART = ` mutation cartCreate($input: CartInput) { cartCreate(input: $input) { cart { id checkoutUrl lines(first: 100) { edges { node { id quantity merchandise { ... on ProductVariant { id title price { amount currencyCode } product { title featuredImage { url altText } } } } } } } cost { subtotalAmount { amount currencyCode } totalAmount { amount currencyCode } totalTaxAmount { amount currencyCode } } } userErrors { field message } } } `; const ADD_TO_CART = ` mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) { cartLinesAdd(cartId: $cartId, lines: $lines) { cart { id lines(first: 100) { edges { node { id quantity } } } } userErrors { field message } } } `; export async function addToCart(cartId: string, variantId: string, quantity: number) { return storefrontFetch({ query: ADD_TO_CART, variables: { cartId, lines: [{ merchandiseId: variantId, quantity }] }, cache: 'no-store', }); } При переході до оплати редиректимо користувача на cart.checkoutUrl — це хостований чекаут Shopify.
Чому ISR — це ключова фіча для headless-магазину?
Інкрементальна статична регенерація (ISR) дозволяє рендерити сторінки товарів статично при збірці, а потім оновлювати їх по вебхуку від Shopify або по TTL. Такий підхід дає швидкість статики з актуальністю динаміки.
// app/api/revalidate/route.ts — вебхук від Shopify import { revalidateTag } from 'next/cache'; import { NextRequest } from 'next/server'; export async function POST(req: NextRequest) { const hmac = req.headers.get('x-shopify-hmac-sha256'); // Верифікація HMAC... const body = await req.json(); const topic = req.headers.get('x-shopify-topic'); if (topic === 'products/update' || topic === 'products/create') { revalidateTag('products'); revalidateTag(`product-${body.handle}`); } if (topic === 'collections/update') { revalidateTag('collections'); } return new Response('OK'); } На практиці це означає: товар з'явився в Shopify — через секунду він уже на сайті. При цьому HTML сторінки кешується на CDN, LCP падає до 0.5 секунди.
Інтернаціоналізація: одна вітрина на всі країни
Storefront API підтримує директиву @inContext для локалізації цін і контенту:
query getProduct($handle: String!, $country: CountryCode!, $language: LanguageCode!) @inContext(country: $country, language: $language) { product(handle: $handle) { title priceRange { minVariantPrice { amount currencyCode } } } } Процес роботи
- Аудит і архітектура — аналізуємо існуючий магазин, переносимо метаполя та налаштування.
- Проектування API — визначаємо запити, оптимізуємо batch-завантаження.
- Розробка фронту — пишемо компоненти на Next.js, налаштовуємо ISR і кешування.
- Інтеграція кошика — Cart API, cookie, редирект на чекаут.
- Тестування — перевіряємо всі сценарії покупки, швидкість, SEO.
- Деплой — CI/CD з версіонуванням, моніторинг.
Строки орієнтовно
| Етап | Строк |
|---|---|
| MVP (каталог + кошик + чекаут) | 3–4 тижні |
| Повноцінний проєкт (пошук, фільтри, ISR, мультимовність) | 2–3 місяці |
| Підтримка та доопрацювання | за домовленістю |
Порівняння: стандартна тема vs headless
| Критерій | Стандартна тема Shopify | Headless (Next.js + ISR) |
|---|---|---|
| TTFB | 500–800 мс | < 50 мс |
| LCP | 4–6 с | < 1 с |
| Кастомізація URL | Тільки /products/handle | Будь-які патерни |
| Чекаут | Тільки стандартний (Plus — дорого) | Повний контроль через API |
| Анімації | Liquid — обмежено | React/Svelte — без обмежень |
Типові помилки при міграції
- Забувають налаштувати вебхуки на оновлення товарів — контент на сайті застаріває. - Не оптимізують GraphQL-запити — отримують N+1 проблему. - Використовують застарілий Checkout API замість Cart API.Що входить в роботу
Документація — опис API, інструкція з деплою. Доступи — налаштування токенів, вебхуків, DNS. Навчання — консультація для ваших розробників. Гарантія — 6 місяців безкоштовної підтримки з критичних багів. Аудит продуктивності — Lighthouse score не нижче 90.
Чому headless-підхід швидший за Liquid?
Порівняємо: стандартна тема Shopify при кожному запиті рендерить сторінку на сервері (TTFB ~500 мс). Headless з ISR віддає готовий HTML з CDN (TTFB < 50 мс). Анімації та інтерактиви — на клієнті, без перезавантаження. Це дає до 3x різниці в LCP.
Наша команда має 8+ років досвіду з Shopify, понад 50 впроваджень headless-рішень. Використовуємо найкращі практики: React Server Components, Suspense, streaming SSR. Зв'яжіться з нами для оцінки вашого проєкту — розрахуємо строки та вартість індивідуально. Отримайте консультацію з headless-міграції — ми проаналізуємо ваш магазин і запропонуємо архітектуру.