Интеграция 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-миграции — мы проанализируем ваш магазин и предложим архитектуру.