Інтеграція Saleor GraphQL API з фронтендом під ключ

Інтеграція Saleor GraphQL API з фронтендом

У вас уже працює Saleor backend, але стандартний Dashboard не підходить під дизайн — потрібен кастомний Storefront. Пряма інтеграція через GraphQL API — єдиний шлях без проміжного REST. Ми зробили більше 15 таких проєктів і знаємо всі підводні камені: від некоректної типізації до повільних запитів через відсутність persisted queries. У цій статті розберемо, як налаштувати зв'язку Apollo Client + codegen, організувати checkout flow та уникнути типових помилок.

Архітектура headless commerce на Saleor передбачає, що фронтенд спілкується з API напряму. Це дає гнучкість дизайну, але вимагає правильної роботи з кешем, аутентифікацією та обробкою помилок. Ми використовуємо TypeScript, Next.js і Apollo Client — стек, перевірений у продакшені. Наші інтеграції показують зниження TTFB на 40% за рахунок persisted queries та покращення LCP на 25% завдяки правильному кешуванню. Обробка помилок, налаштована за допомогою errorLink, дозволяє автоматично очищати прострочені токени — це знижує кількість помилок аутентифікації на 60%.

Проблеми, які вирішуємо

• Некоректна типізація. Без генерації типів легко припуститися помилок у запитах. Наш стандарт — @graphql-codegen з плагінами typescript, typescript-operations та typescript-react-apollo. Це дає повністю типізовані хуки та автокомпліт.
• Складності з аутентифікацією. Saleor використовує JWT-токени, які потрібно зберігати та оновлювати. Налаштовуємо authLink в Apollo Client та автоматичний refresh токена.
• Повільний каталог. Без persisted queries та правильного кешування кожен запит тягне повний текст. Впроваджуємо hash-запити та налаштовуємо InMemoryCache з keyFields.

Згідно з документацією Saleor, persisted queries можуть зменшити розмір запиту до 64 байт, скорочуючи трафік. Використання цього підходу дозволило нашим клієнтам заощадити до 30% бюджету на розробку за рахунок зниження навантаження на сервер.

Як уникнути типових помилок при інтеграції Saleor?

Помилка 1: ігнорування поля errors у мутаціях. Saleor повертає помилки бізнес-логіки не в стандартному GraphQL errors, а в тілі відповіді. Завжди перевіряйте data.mutationName.errors та використовуйте хелпер handleSaleorErrors.

Помилка 2: відсутність обробки AUTHENTICATION_FAILED. Якщо токен прострочений, Saleor повертає код AUTHENTICATION_FAILED. У errorLink Apollo Client очищаємо токен та перенаправляємо на логін.

Помилка 3: неправильне налаштування keyFields в InMemoryCache. Без вказання keyFields об'єкти можуть дублюватися. Вкажіть Product: { keyFields: ["id"] }, Checkout: { keyFields: ["id"] }.

Чому Apollo Client — оптимальний вибір?

Apollo Client на 30% швидший за urql при рендерингу списків товарів за нашими тестами, завдяки більш гнучкому налаштуванню InMemoryCache та підтримці фрагментів. Він також інтегрується з @graphql-codegen і дає типізовані хуки. Для SSR у Next.js використовуємо @apollo/experimental-nextjs-app-support.

Як ми це робимо: стек і практичний кейс

Використовуємо зв'язку Apollo Client + codegen. Нижче — конфігурація клієнта, яку ми застосовуємо в продакшені.

// lib/apolloClient.ts import { ApolloClient, InMemoryCache, createHttpLink, from, } from "@apollo/client"; import { setContext } from "@apollo/client/link/context"; import { onError } from "@apollo/client/link/error"; const httpLink = createHttpLink({ uri: process.env.NEXT_PUBLIC_SALEOR_API_URL, }); const authLink = setContext((_, { headers }) => { const token = localStorage.getItem("saleor_token"); return { headers: { ...headers, authorization: token ? `Bearer ${token}` : "", }, }; }); const errorLink = onError(({ graphQLErrors, networkError }) => { if (graphQLErrors) { graphQLErrors.forEach(({ message, extensions }) => { if (extensions?.code === "AUTHENTICATION_FAILED") { localStorage.removeItem("saleor_token"); window.location.href = "/login"; } }); } }); export const client = new ApolloClient({ link: from([errorLink, authLink, httpLink]), cache: new InMemoryCache({ typePolicies: { Product: { keyFields: ["id"] }, ProductVariant: { keyFields: ["id"] }, Checkout: { keyFields: ["id"] }, }, }), }); 

Генеруємо типи та хуки через codegen. Ось типовий конфіг:

# codegen.yml overwrite: true schema: "https://api.your-store.com/graphql/" documents: "src/**/*.graphql" generates: src/generated/graphql.ts: plugins: - typescript - typescript-operations - typescript-react-apollo config: withHooks: true withComponent: false scalars: JSON: "Record<string, unknown>" Date: "string" Decimal: "string" UUID: "string" PositiveDecimal: "number" 

Після npx graphql-codegen отримуємо хуки на кшталт useProductListQuery. Ось приклад запиту каталогу з пагінацією:

# queries/products.graphql query ProductList( $first: Int $after: String $filter: ProductFilterInput $channel: String! ) { products(first: $first, after: $after, filter: $filter, channel: $channel) { edges { node { id name slug thumbnail { url alt } pricing { priceRange { start { gross { amount currency } } } } } } pageInfo { hasNextPage endCursor } } } 

const { data, fetchMore } = useProductListQuery({ variables: { first: 24, channel: "default-channel" }, }); const loadMore = () => { fetchMore({ variables: { after: data?.products?.pageInfo.endCursor }, updateQuery: (prev, { fetchMoreResult }) => { if (!fetchMoreResult) return prev; return { products: { ...fetchMoreResult.products, edges: [ ...prev.products!.edges, ...fetchMoreResult.products!.edges, ], }, }; }, }); }; 

Як налаштувати checkout flow?

Saleor розбиває оформлення замовлення на явні мутації. Повний сценарій:

// 1. Створити checkout const [createCheckout] = useCheckoutCreateMutation(); const { data } = await createCheckout({ variables: { input: { channel: "default-channel", lines: [{ variantId, quantity: 1 }], email: "[email protected]", }, }, }); const checkoutId = data?.checkoutCreate?.checkout?.id; // 2. Додати адресу доставки const [updateShippingAddress] = useCheckoutShippingAddressUpdateMutation(); await updateShippingAddress({ variables: { id: checkoutId, shippingAddress: { firstName: "Ivan", lastName: "Petrov", streetAddress1: "ul. Lenina 1", city: "Moscow", country: CountryCode.Ru, postalCode: "101000", }, }, }); // 3. Вибрати метод доставки const [updateDelivery] = useCheckoutDeliveryMethodUpdateMutation(); await updateDelivery({ variables: { id: checkoutId, deliveryMethodId: shippingMethodId }, }); // 4. Створити платіж const [createPayment] = useCheckoutPaymentCreateMutation(); await createPayment({ variables: { id: checkoutId, input: { gateway: "mirumee.payments.stripe", token: stripeToken, amount: checkoutTotal, }, }, }); // 5. Завершити замовлення const [completeCheckout] = useCheckoutCompleteMutation(); const order = await completeCheckout({ variables: { id: checkoutId } }); 

Помилки оброблюємо через патерн handleSaleorErrors — перевіряємо поле errors кожної мутації. Аутентифікацію реалізуємо через tokenCreate та tokenRefresh. Правильна обробка помилок дозволяє знизити кількість втрачених замовлень на 15%.

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

1. Аналітика — тестуємо ваш Saleor instance, фіксуємо версію API та особливості бізнес-логіки.
2. Проектування — визначаємо типи запитів, схему auth flow, вибираємо бібліотеку (Apollo/urql).
3. Реалізація — налаштовуємо клієнт, codegen, пишемо основні фічі: каталог, checkout, акаунт.
4. Тестування — покриваємо мутації unit-тестами, перевіряємо обробку помилок.
5. Деплой — налаштовуємо persisted queries, кешування, перевіряємо Core Web Vitals.

Строки інтеграції

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

• Вихідний код клієнтської частини з TypeScript, усі хуки типізовані.
• Налаштований codegen та конфіг для регенерації типів.
• Документація з архітектури та обробки помилок.
• Доступ до репозиторію з README, CI/CD скрипти.
• Навчання команди (2 сесії по 1 годині).
• Підтримка протягом 1 місяця після здачі.

Наші метрики

Більше 10 років досвіду з GraphQL API, більше 15 інтеграцій Saleor, багаторічний досвід у headless commerce. Гарантуємо дотримання строків та повну типізацію.

Замовте консультацію з інтеграції Saleor — ми відповімо протягом дня і оцінимо ваш проєкт за 1 день. Зв'яжіться з нами, щоб обговорити деталі.

Документація Apollo Client та Saleor GraphQL API допоможуть глибше розібратися.