Інтеграція Shopify Storefront API з кастомним фронтендом

Інтеграція 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
      }
    }
  }
}

Процес роботи

1. Аудит і архітектура — аналізуємо існуючий магазин, переносимо метаполя та налаштування.
2. Проектування API — визначаємо запити, оптимізуємо batch-завантаження.
3. Розробка фронту — пишемо компоненти на Next.js, налаштовуємо ISR і кешування.
4. Інтеграція кошика — Cart API, cookie, редирект на чекаут.
5. Тестування — перевіряємо всі сценарії покупки, швидкість, SEO.
6. Деплой — CI/CD з версіонуванням, моніторинг.

Строки орієнтовно

Порівняння: стандартна тема vs headless

Що входить в роботу

Документація — опис 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-міграції — ми проаналізуємо ваш магазин і запропонуємо архітектуру.