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

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

Saleor надає єдиний GraphQL endpoint для всіх операцій — каталог, кошик, checkout, платежі, акаунт. Фронтенд працює безпосередньо з цим API без проміжного REST шару. Інтеграція будується на Apollo Client або urql, з генерацією типів через @graphql-codegen.

Налаштування Apollo Client

// 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 --config codegen.yml

Результат — повністю типізовані хуки на кшталт useProductListQuery, useCheckoutCreateMutation та ін.

Каталог: список товарів з пагінацією

# 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 розділяє checkout на явні мутації. Повний flow:

// 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 } });

Аутентифікація користувачів

// Логін
const [tokenCreate] = useTokenCreateMutation();
const { data } = await tokenCreate({
  variables: { email, password },
});
const { token, refreshToken, errors } = data!.tokenCreate!;

if (!errors?.length) {
  localStorage.setItem("saleor_token", token!);
  localStorage.setItem("saleor_refresh_token", refreshToken!);
}

// Оновлення токена
const [tokenRefresh] = useTokenRefreshMutation();
const refreshed = await tokenRefresh({
  variables: { token: localStorage.getItem("saleor_refresh_token")! },
});

Обробка помилок Saleor

Saleor повертає помилки не через стандартний GraphQL errors, а через поле errors у тілі відповіді мутації. Паттерн обробки:

function handleSaleorErrors<T extends { errors: SaleorError[] }>(
  result: T | null | undefined,
  onSuccess: (data: T) => void
) {
  if (!result) return;
  if (result.errors.length > 0) {
    result.errors.forEach((err) => {
      console.error(`${err.field}: ${err.message} (${err.code})`);
    });
    return;
  }
  onSuccess(result);
}

Продуктивність

• Saleor підтримує persisted queries — відправляти хеш замість тексту запиту
• Використовуйте fragments для повторного використання полів між запитами
• InMemoryCache з правильними keyFields виключає дублювання даних
• Для SSR (Next.js) — @apollo/experimental-nextjs-app-support або getStaticProps з client.query()

Часові рамки інтеграції