Інтеграція 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 тижні. Отримайте консультацію по вашому проєкту — зв'яжіться з нами для безкоштовної оцінки.