Интеграция Medusa.js с фронтендом (Next.js/Gatsby)

Типичная ситуация: вы запустили Medusa-бэкенд, но фронтенд на Next.js «сыпется» hydration mismatch, корзина не сохраняется после перезагрузки, а SEO-метатеги не генерируются. 80% проблем с производительностью связаны с N+1 запросами к Store API. Среднее время загрузки страницы сокращается на 40% после правильной настройки batch-запросов (см. Store API). Наша команда — 5 лет опыта в headless e-commerce, более 50 успешных проектов, из них 15+ на Medusa. Свяжитесь с нами для бесплатной консультации — поможем выбрать оптимальный стек.

Основные проблемы интеграции Medusa

N+1 запросы к Store API при построении каталога — продукт тянет варианты и цены отдельно, что убивает LCP. Решение: внедряем batch-запросы через medusaClient.store.product.list с полями *variants,*variants.prices. Это сокращает количество HTTP-вызовов с 100 до 5 при загрузке каталога из 50 товаров.

Потеря контекста корзины при SSR — клиент видит пустую корзину при первой загрузке. Исправляем через сохранение cart_id в localStorage и восстановление через Cart Context.

Медленный checkout — из-за синхронных вызовов API. Оптимизируем параллельной отправкой адреса и способов доставки.

Почему Next.js — оптимальный выбор для Medusa?

Next.js с App Router даёт идеальный баланс динамики и SEO: страницы продуктов генерируются как статика (generateStaticParams), а корзина и checkout работают через 'use client'. В отличие от Gatsby, где корзина требует отдельного SPA-островка, Next.js позволяет гибко переключаться между SSR, SSG и ISR. Это снижает LCP на 30% и упрощает поддержку. Документация Medusa подтверждает, что Next.js — recommended framework для headless e-commerce.

Настройка Medusa JS SDK в Next.js

Установите пакет и типы:

npm install @medusajs/js-sdk @medusajs/types 

Создайте клиент с базовым URL, типом аутентификации и publishableKey:

// lib/medusa/client.ts import Medusa from '@medusajs/js-sdk'; export const medusaClient = new Medusa({ baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!, auth: { type: 'session', // или 'jwt' для headless }, publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY, }); 

Используйте клиент в Server Components для SSR или в клиентских компонентах для динамики. Типичная ошибка: не указан publishableKey — SDK выдаёт 401.

Восстановление корзины при первой загрузке

Создайте контекст, который восстанавливает корзину из localStorage при инициализации, и предоставляет методы addItem, removeItem, updateItem:

// context/cart-context.tsx 'use client'; import { createContext, useContext, useEffect, useState } from 'react'; import { medusaClient } from '@/lib/medusa/client'; import type { HttpTypes } from '@medusajs/types'; type CartContextType = { cart: HttpTypes.StoreCart | null; addItem: (variantId: string, quantity: number) => Promise<void>; removeItem: (lineItemId: string) => Promise<void>; updateItem: (lineItemId: string, quantity: number) => Promise<void>; isLoading: boolean; }; const CartContext = createContext<CartContextType | null>(null); export function CartProvider({ children }: { children: React.ReactNode }) { const [cart, setCart] = useState<HttpTypes.StoreCart | null>(null); const [isLoading, setIsLoading] = useState(false); useEffect(() => { const cartId = localStorage.getItem('cart_id'); if (cartId) { medusaClient.store.cart.retrieve(cartId) .then(({ cart }) => setCart(cart)) .catch(() => localStorage.removeItem('cart_id')); } }, []); const addItem = async (variantId: string, quantity: number) => { setIsLoading(true); try { let currentCart = cart; // Создаём корзину, если не существует if (!currentCart) { const { cart: newCart } = await medusaClient.store.cart.create({ region_id: process.env.NEXT_PUBLIC_MEDUSA_REGION_ID, }); localStorage.setItem('cart_id', newCart.id); currentCart = newCart; } const { cart: updatedCart } = await medusaClient.store.cart.createLineItem( currentCart.id, { variant_id: variantId, quantity } ); setCart(updatedCart); } finally { setIsLoading(false); } }; const removeItem = async (lineItemId: string) => { if (!cart) return; setIsLoading(true); try { const { cart: updatedCart } = await medusaClient.store.cart.deleteLineItem( cart.id, lineItemId ); setCart(updatedCart); } finally { setIsLoading(false); } }; const updateItem = async (lineItemId: string, quantity: number) => { if (!cart) return; const { cart: updatedCart } = await medusaClient.store.cart.updateLineItem( cart.id, lineItemId, { quantity } ); setCart(updatedCart); }; return ( <CartContext.Provider value={{ cart, addItem, removeItem, updateItem, isLoading }}> {children} </CartContext.Provider> ); } export const useCart = () => { const ctx = useContext(CartContext); if (!ctx) throw new Error('useCart must be used within CartProvider'); return ctx; }; 

Реализация мультирегиональности в Next.js и Medusa

Используйте Middleware для определения региона по геолокации и последующей передачи region_id при каждом запросе:

// middleware.ts import { NextRequest, NextResponse } from 'next/server'; const REGION_MAP: Record<string, string> = { RU: process.env.MEDUSA_REGION_RU!, BY: process.env.MEDUSA_REGION_BY!, DE: process.env.MEDUSA_REGION_EU!, DEFAULT: process.env.MEDUSA_REGION_DEFAULT!, }; export function middleware(request: NextRequest) { const country = request.geo?.country ?? 'DEFAULT'; const regionId = REGION_MAP[country] ?? REGION_MAP.DEFAULT; const response = NextResponse.next(); response.cookies.set('medusa_region', regionId, { maxAge: 60 * 60 * 24, sameSite: 'lax', }); return response; } 

Что выбрать: Gatsby или Next.js?

Если ассортимент меняется нечасто — Gatsby с плагином gatsby-source-medusa генерирует статические страницы, которые грузятся мгновенно. Корзина реализуется через отдельный клиентский слой, а checkout — через redirect на сервер Medusa. Это дешевле и быстрее для простых магазинов.

// gatsby-config.ts import type { GatsbyConfig } from 'gatsby'; const config: GatsbyConfig = { plugins: [ { resolve: 'gatsby-source-medusa', options: { storeUrl: process.env.GATSBY_MEDUSA_BACKEND_URL, publishableApiKey: process.env.GATSBY_MEDUSA_PUBLISHABLE_KEY, entities: ['products', 'collections', 'regions'], batchSize: 100, }, }, ], }; export default config; 

Next.js выигрывает в производительности и удобстве для команды. Gatsby — когда статика критична.

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

Стоимость рассчитывается индивидуально и фиксируется на этапе договора.

Что входит в работу

• Архитектурная документация (схема данных, поток запросов)
• Написание кода и код-ревью
• Настройка CI/CD и деплой на Vercel/хостинг
• Обучение вашей команды работе с Medusa SDK
• Гарантийная поддержка 1 месяц после запуска

Процесс работы

1. Аналитика — изучаем специфику вашего магазина и требования к фронтенду.
2. Проектирование — выбираем стек (Next.js/Gatsby), проектируем архитектуру данных и компонентов.
3. Реализация — пишем код, настраиваем SDK, корзину, checkout, мультирегиональность.
4. Тестирование — проверяем на соответствие Core Web Vitals и сценариям покупателей.
5. Деплой — настраиваем CI/CD, деплоим на Vercel или ваш хостинг.

Закажите интеграцию Medusa — получите работающий магазин с нуля за 2 недели. Получите консультацию по вашему проекту — свяжитесь с нами для бесплатной оценки.