What's new
kishansavaliyakb@gmail.com
Chat on WhatsApp
Toggle Nav
My Cart
mage2react — Headless Magento 2 Storefront (Astro + React)

mage2react — Headless Magento 2 Storefront (Astro + React)

A production-ready, open-source headless storefront for Magento 2 - Luma parity, Hyva-beating speed, built on Astro 5 + React 19 + Tailwind v4. One command boots the full stack in Docker. TTFB under 150 ms. Zero client JS by default. Strict CSP. 2026 Google SEO covered out of ...

Magento 2.4.7–2.4.8 PHP 8.2–8.4 Free

Key Features:

  • Built for Magento 2
  • MEQP Compliant
  • Hyva + Luma Ready
  • Free Forever

Additional Services

$0.00
In stock
SKU
panth-mage2react
Links
Pay with Wise
Lifetime Updates Every Magento release
1-Year Free Support Email + WhatsApp
Adobe-Certified Magento 2 Developer
Free Forever No subscription, no upsell
What you get

Everything in the box

Built-in from day one. No add-ons, no upsell, no licence keys to renew.

Built for Magento 2

A production-ready, open-source headless storefront for Magento 2 - Luma parity, Hyva-beating speed, built on Astro 5 + React 19 + Tailwind v4.

MEQP Compliant

Adobe Magento Extension Quality Program — passes with zero severity-10 violations.

Hyva + Luma Ready

Vanilla JS, no jQuery dependency. Drop-in compatible with both default Luma and Hyva themes.

Free Forever

Lifetime updates with every Magento release. No subscription, no licence keys, no upsells.

Overview

mage2react is an open-source headless React storefront for Magento 2 that ships Luma feature parity on Astro 5, React 19, and Tailwind CSS v4.

The stack pairs Magento GraphQL as the data layer with Astro SSR and React 19 islands, so home, category, product detail, search, cart, customer account, and multi-step checkout render as small HTML pages with zero client JS by default. Local TTFB stays under 150 ms on the home route, and a single docker compose up boots Magento, MySQL, OpenSearch, Redis, and the Astro frontend together. mage2react targets Magento 2.4.4–2.4.9 with PHP 8.1–8.4 and works alongside Adobe Commerce installs.

React and Astro adapters for 38 first-party Panth Magento extensions drop in through a single <PanthSlot> tag, so banners, testimonials, FAQs, product tabs, smart badges, and mega menus reuse the same backend modules already shipped with Hyvä storefronts. The 2026 Google SEO checklist is covered: JSON-LD @graph, canonical, hreflang, OpenGraph, dynamic sitemap.xml, and strict CSP. PWA Studio teams gain a lighter alternative without Apollo or Webpack.

  • Best for: Magento merchants who want a headless React storefront without months of PWA Studio setup.
  • Best for: Agencies replacing Luma with a Tailwind v4 + React 19 frontend on tight deadlines.
  • Best for: Adobe Commerce projects that demand strict CSP, Zod-validated GraphQL, and SSR by default.

Why mage2react

  • Luma's frontend is dead weight. Magento's default theme ships megabytes of RequireJS + KnockoutJS + jQuery on every page. Core Web Vitals suffer. SEO rankings suffer.
  • Hyva is good — but still phtml. Buys you speed, keeps you in layout XML + Alpine.js. No React, no Tailwind v4, no modern DX.
  • PWA Studio is heavy. Apollo + Workbox + MediaStorm + Webpack config — months to get productive.
  • mage2react gives you Astro 5 + React 19 + Tailwind v4 Oxide with Magento GraphQL as the data layer, no framework lock-in, Docker Compose deploy, and a full React adapter surface for 38 first-party Panth extensions. Start a real project by next sprint.

What you get

mage2react is a headless React storefront for Magento 2 with Luma feature parity and 38 Panth module adapters.

  • Astro 5 SSR with React 19 islands and Tailwind v4 Oxide engine for sub-100 ms rebuilds.
  • Magento GraphQL drives home, category, PDP, search, cart, account, and multi-step checkout.
  • 38 Panth extension adapters wired through a single <PanthSlot> tag.
  • 2026 SEO defaults: JSON-LD @graph, canonical, OpenGraph, dynamic sitemap.xml.
  • Strict CSP, HttpOnly token cookie, Zod-validated GraphQL, DOMPurify on Magento HTML.
  • One docker compose up boots Magento 2.4.x, MySQL, OpenSearch, Redis, and Astro.

mage2react — The Fastest Headless Magento 2 Storefront

A production-ready, open-source headless storefront for Magento 2 — Luma parity, Hyva-beating speed, built on Astro 5 + React 19 + Tailwind v4. One command boots the full stack in Docker. TTFB under 150 ms. Zero client JS by default. Strict CSP. 2026 Google SEO covered out of the box. Ships with React/Astro adapters for 38 Panth Magento extensions so banners, testimonials, FAQs, product tabs, smart badges, mega-menus, and dozens more drop into the storefront via a single <PanthSlot> tag.

Stop fighting Luma. Stop building PWA Studio. mage2react is a drop-in replacement that serves your whole storefront — home, category, PDP, search, cart, customer account, multi-step checkout — as tiny HTML pages with React islands only where needed. All data via Magento GraphQL. All security hardened by default.

Feature Matrix

Storefront

  • Home, category listings, product detail (all types), CMS pages
  • Magento-standard URL structure (/{url_key}.html) via urlResolver
  • Configurable products with color/size swatches + variant image swap
  • Bundle, grouped, downloadable, virtual, simple — all supported
  • Mega menu pulled live from Magento category tree
  • Mobile hamburger drawer (zero-JS <details> based)
  • Layered navigation + sort + pagination on category & search
  • Search results with noindex, search autocomplete in header
  • Recently viewed strip (localStorage, DNT-respecting)
  • Quick view modal with Add to Cart direct from grid
  • Product reviews (list + submit) with star ratings
  • CMS blocks rendered via GraphQL, sanitized via DOMPurify
  • Dynamic widget slots — drop any Panth module into any page by identifier

Commerce

  • Real Magento-backed cart (createEmptyCart, addProductsToCart)
  • Luma-style mini-cart dropdown (+/- qty, trash icon, auto-close)
  • Full cart page with coupon application and taxes
  • Multi-step React checkout: shipping → payment → place order → success
  • Guest checkout supported (existing-account email is non-blocking)
  • Saved-address picker for logged-in customers
  • Logged-in customer carts sync end-to-end (middleware + /api/graphql proxy + SSR)
  • Native reorder via reorderItems() — works for every product type
  • Virtual-only carts skip the shipping step
  • Out-of-stock handling — banner replaces buy box
  • Compare products (Magento's native compare list GraphQL)
  • Wishlist heart button

Customer Account

  • Login, register, forgot password, password reset
  • Account dashboard, edit info, change password, newsletter
  • Order history + order detail with Reorder
  • Address book (add / edit / delete, default shipping/billing)
  • Account menu dropdown in header (logged in / out variants)

SEO (2026 Google Rules)

  • Unique <title> + <meta description> per page
  • <link rel="canonical"> (strips ?page=1, sort, pageSize)
  • Open Graph + Twitter summary_large_image cards
  • JSON-LD @graph root: Organization, WebSite + SearchAction, BreadcrumbList, Product (with aggregateRating, priceValidUntil, itemCondition, brand), ItemList, CollectionPage, WebPage, SearchResultsPage, FAQPage, Article
  • Dynamic sitemap.xml with <image:image> per product
  • robots.txt with Host: directive and surgical disallows
  • opensearch.xml for browser search integration
  • <link rel="prev"> / rel="next" pagination
  • Robots meta with max-snippet, max-image-preview:large, max-video-preview:-1
  • Semantic HTML, one <h1> per page
  • <html lang> from storeConfig.locale
  • View Transitions API for perceived speed
  • nofollow on placeholder links

Security

  • Strict CSP on Astro pages; loose CSP only for proxied Magento pages (auto-switched via server-only X-Mage2React-Proxied header that's stripped before egress)
  • DOMPurify on every Magento HTML string
  • Zod validation on every GraphQL response
  • HttpOnly customer-token cookie (never JS-accessible)
  • Customer API routed through /api/graphql proxy (token injected server-side)
  • X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin
  • Permissions-Policy disabling camera / mic / payment / sensors
  • COOP / CORP: same-origin
  • Origin-check CSRF (Astro checkOrigin: true)
  • Rate-limited public endpoints (newsletter, contact, forms)
  • Stripped hop-by-hop headers on the proxy path; 25 MB body cap; 10 s timeout

Performance

  • Astro 5 SSR (Node adapter, standalone mode)
  • React 19 islands (client:idle / client:visible) — zero JS default
  • Tailwind v4 Oxide engine (sub-100 ms rebuilds)
  • System font stack (no FOUT, no external requests)
  • <link rel="preload"> for LCP image with fetchpriority="high"
  • width + height + loading on every <img> (no CLS)
  • HTTP cache headers on sitemap / robots / opensearch
  • Service worker with network-first HTML, stale-while-revalidate assets
  • Hydration-mismatch-safe: useId, mount-gated client state

Developer Experience

  • TypeScript strict + noUncheckedIndexedAccess
  • Zod-validated GraphQL responses (compile-time + runtime)
  • Docker Compose — one command boots the full stack
  • graphql-request (tiny) — no Apollo
  • nanostores + @nanostores/react (~5 KB gz)
  • PWA manifest + service worker + offline fallback
  • Accessibility primitives: skip link, focus trap, live regions, reduced-motion
  • Global toast system, error boundaries, skeleton loaders

Performance

Measured locally (curl --resolve to bypass macOS mDNS):

Route TTFB Payload
Home ~125 ms 56 KB
Category ~445 ms 40 KB
Product ~113 ms 48 KB
Sitemap ~85 ms 37 KB
Core Web Vital Target How
LCP ≤ 2.0 s Hero image preload, system fonts, no render-blocking JS
CLS ≤ 0.05 Explicit width/height, aspect-ratio boxes, system font stack
INP ≤ 150 ms Zero client JS default, client:idle / client:visible hydration

Panth Modules Bundled

mage2react installs and adapts 38 first-party Panth Magento extensions (by mage2kishan). Each shipped Magento extension gets a matching Panth_<Name>React companion that wires it into the React storefront — proper <sequence> dependency, typed GraphQL queries, and drop-in Astro/React components.

# Composer package Magento module React companion Storefront?
SEO & Marketing
1 mage2kishan/module-advanced-seo Panth_AdvancedSeo Panth_AdvancedSeoReact
2 mage2kishan/module-pagebuilder-ai Panth_PagebuilderAi Panth_PagebuilderAiReact admin-only
3 mage2kishan/module-corewebvitals Panth_Corewebvitals Panth_CorewebvitalsReact
4 mage2kishan/module-smart-badge Panth_SmartBadge Panth_SmartBadgeReact
5 mage2kishan/module-testimonials Panth_Testimonials Panth_TestimonialsReact
Checkout & Cart
6 mage2kishan/module-advancedcart Panth_Advancedcart Panth_AdvancedcartReact
7 mage2kishan/module-checkout-extended Panth_CheckoutExtended Panth_CheckoutExtendedReact
8 mage2kishan/module-checkout-success Panth_CheckoutSuccess Panth_CheckoutSuccessReact
9 mage2kishan/module-custom-options Panth_CustomOptions Panth_CustomOptionsReact
10 mage2kishan/module-extra-fee Panth_ExtraFee Panth_ExtraFeeReact
11 mage2kishan/module-zipcode-validation Panth_ZipcodeValidation Panth_ZipcodeValidationReact
Order Management
12 mage2kishan/module-order-attachments Panth_OrderAttachments Panth_OrderAttachmentsReact
13 mage2kishan/module-order-cleanup Panth_OrderCleanup Panth_OrderCleanupReact admin-only
14 mage2kishan/module-ordered-items Panth_OrderedItems Panth_OrderedItemsReact admin-only
Theme & UI
15 mage2kishan/module-banner-slider Panth_BannerSlider Panth_BannerSliderReact
16 mage2kishan/module-mega-menu Panth_MegaMenu Panth_MegaMenuReact
17 mage2kishan/module-footer Panth_Footer Panth_FooterReact
18 mage2kishan/module-not-found-page Panth_NotFoundPage Panth_NotFoundPageReact
19 mage2kishan/module-notification-bar Panth_NotificationBar Panth_NotificationBarReact
20 mage2kishan/module-theme-customizer Panth_ThemeCustomizer Panth_ThemeCustomizerReact
Product Display
21 mage2kishan/module-product-slider Panth_ProductSlider Panth_ProductSliderReact
22 mage2kishan/module-productgallery Panth_Productgallery Panth_ProductgalleryReact
23 mage2kishan/module-producttabs Panth_Producttabs Panth_ProducttabsReact
24 mage2kishan/module-quickview Panth_Quickview Panth_QuickviewReact
25 mage2kishan/module-search-autocomplete Panth_SearchAutocomplete Panth_SearchAutocompleteReact
26 mage2kishan/module-imageoptimizer Panth_Imageoptimizer Panth_ImageoptimizerReact
Customer Engagement
27 mage2kishan/module-advanced-contact-us Panth_AdvancedContactUs Panth_AdvancedContactUsReact
28 mage2kishan/module-dynamic-forms Panth_DynamicForms Panth_DynamicFormsReact
29 mage2kishan/module-faq Panth_Faq Panth_FaqReact
30 mage2kishan/module-live-activity Panth_LiveActivity Panth_LiveActivityReact
31 mage2kishan/module-low-stock-notification Panth_LowStockNotification Panth_LowStockNotificationReact
32 mage2kishan/module-price-drop-alert Panth_PriceDropAlert Panth_PriceDropAlertReact
33 mage2kishan/module-product-attachments Panth_ProductAttachments Panth_ProductAttachmentsReact
34 mage2kishan/module-whatsapp Panth_Whatsapp Panth_WhatsappReact
Admin & Performance
35 mage2kishan/module-cachemanager Panth_Cachemanager Panth_CachemanagerReact admin-only
36 mage2kishan/module-core Panth_Core Panth_CoreReact admin-only
37 mage2kishan/module-malware-scanner Panth_MalwareScanner Panth_MalwareScannerReact admin-only
38 mage2kishan/module-performance-optimizer Panth_PerformanceOptimizer Panth_PerformanceOptimizerReact (perf hints)

One-liner to install all 38:

docker exec <project>_php composer require --update-no-dev --no-interaction \
 mage2kishan/module-advanced-seo mage2kishan/module-pagebuilder-ai \
 mage2kishan/module-corewebvitals mage2kishan/module-smart-badge \
 mage2kishan/module-testimonials mage2kishan/module-advancedcart \
 mage2kishan/module-checkout-extended mage2kishan/module-checkout-success \
 mage2kishan/module-custom-options mage2kishan/module-extra-fee \
 mage2kishan/module-zipcode-validation mage2kishan/module-order-attachments \
 mage2kishan/module-order-cleanup mage2kishan/module-ordered-items \
 mage2kishan/module-banner-slider mage2kishan/module-mega-menu \
 mage2kishan/module-footer mage2kishan/module-not-found-page \
 mage2kishan/module-notification-bar mage2kishan/module-theme-customizer \
 mage2kishan/module-product-slider mage2kishan/module-productgallery \
 mage2kishan/module-producttabs mage2kishan/module-quickview \
 mage2kishan/module-search-autocomplete mage2kishan/module-imageoptimizer \
 mage2kishan/module-advanced-contact-us mage2kishan/module-dynamic-forms \
 mage2kishan/module-faq mage2kishan/module-live-activity \
 mage2kishan/module-low-stock-notification mage2kishan/module-price-drop-alert \
 mage2kishan/module-product-attachments mage2kishan/module-whatsapp \
 mage2kishan/module-cachemanager mage2kishan/module-core \
 mage2kishan/module-malware-scanner mage2kishan/module-performance-optimizer

The full resolved dependency set is captured in src/composer.json (tracked in this repo) and the lockfile at src/composer.lock.

Dynamic Widget Slots — &lt;PanthSlot /&gt;

Drop Panth-module-backed widgets into any Astro page, CMS template, category description, or product description by identifier:

---
import PanthSlot from "~/components/panth/PanthSlot.astro";
---

<!-- Banner slider identified by its `panth_banner_slider.identifier` -->
<PanthSlot identifier="banner-slider:home-hero" />

<!-- 6 featured testimonials -->
<PanthSlot identifier="testimonials:6" />

<!-- FAQ block for a specific admin category -->
<PanthSlot identifier="faq:general" />

<!-- A dynamic form by admin url_key -->
<PanthSlot identifier="form:custom-contact" />

<!-- Core Magento CMS block -->
<PanthSlot identifier="cms-block:home-bottom" />

<!-- Product carousel for a specific slider slug -->
<PanthSlot identifier="product-slider:bestsellers" />

<!-- Announcement bar -->
<PanthSlot identifier="notification-bar" />

<!-- Live-activity badge on a PDP -->
<PanthSlot identifier="live-activity:WJ12" />

<!-- Product attachments on a PDP -->
<PanthSlot identifier="attachments:WJ12" />

Unknown identifiers render nothing. All widgets read from Magento GraphQL via Zod-guarded safeParse — if the underlying Panth module is missing or disabled, the slot silently renders empty.

Project Layout

mage2react/
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── nginx.conf
├── SETUP.md
│
├── src/
│ ├── composer.json # tracked: exact extension set
│ ├── composer.lock # tracked
│ └── app/code/Panth/ # 39 custom modules
│ ├── React/ # the core Panth_React module
│ ├── AdvancedSeoReact/
│ ├── BannerSliderReact/
│ ├── CheckoutExtendedReact/
│ ├── FaqReact/
│ ├── ... # 38 companion modules
│ └── WhatsappReact/
│
└── frontend/
 ├── Dockerfile
 ├── astro.config.mjs
 ├── tsconfig.json
 ├── public/ # manifest, sw.js, logo, favicon
 └── src/
 ├── middleware.ts # CSP + security + cart bootstrap
 ├── layouts/Base.astro
 ├── components/
 │ ├── panth/ # all Panth companions
 │ │ ├── PanthSlot.astro
 │ │ ├── banner-slider/
 │ │ ├── testimonials/
 │ │ ├── faq/
 │ │ ├── dynamic-forms/
 │ │ ├── smart-badge/
 │ │ ├── mega-menu/
 │ │ ├── product-slider/
 │ │ ├── productgallery/
 │ │ ├── producttabs/
 │ │ ├── quickview/
 │ │ ├── search-autocomplete/
 │ │ ├── notification-bar/
 │ │ ├── theme-customizer/
 │ │ ├── whatsapp/
 │ │ ├── live-activity/
 │ │ ├── low-stock-notification/
 │ │ ├── price-drop-alert/
 │ │ ├── product-attachments/
 │ │ ├── order-attachments/
 │ │ ├── advanced-contact-us/
 │ │ ├── advancedcart/
 │ │ ├── checkout-extended/
 │ │ ├── checkout-success/
 │ │ ├── custom-options/
 │ │ ├── extra-fee/
 │ │ ├── zipcode-validation/
 │ │ ├── advanced-seo/
 │ │ ├── cwv/
 │ │ └── not-found/
 │ ├── catalog/
 │ ├── cart/
 │ ├── checkout/
 │ ├── compare/
 │ ├── customer/
 │ ├── product/
 │ ├── seo/
 │ ├── a11y/
 │ ├── system/
 │ ├── cms/
 │ └── ProductCard.astro
 ├── pages/
 │ ├── index.astro
 │ ├── [...slug].astro
 │ ├── search.astro
 │ ├── compare.astro
 │ ├── contact.astro
 │ ├── faq.astro
 │ ├── testimonials.astro
 │ ├── offline.astro
 │ ├── 404.astro
 │ ├── checkout/
 │ ├── customer/
 │ ├── sales/order/
 │ ├── wishlist/index.astro
 │ ├── api/ # graphql proxy, cart, wishlist, reviews, panth/*
 │ ├── sitemap.xml.ts
 │ ├── robots.txt.ts
 │ └── opensearch.xml.ts
 ├── lib/ # graphql, queries-*, stores, sanitize, jsonld
 └── styles/global.css

Security Model

  • Strict CSP on Astro pages: default-src 'self', script-src 'self' 'unsafe-inline' (inline-only), object-src 'none', frame-ancestors 'none', upgrade-insecure-requests.
  • Loose CSP only for Magento-proxied pages (auto-detected via a server-only header stripped before egress).
  • DOMPurify sanitizes every Magento HTML string (product descriptions, CMS blocks, banners, testimonials, FAQ answers).
  • Zod schemas validate every GraphQL response at runtime.
  • HttpOnly cookies for customer tokens. Server-side /api/graphql proxy injects auth; the token never touches JS.
  • Rate-limited public endpoints (newsletter, contact, forms).
  • Proxy hardening: drops hop-by-hop headers, 25 MB cap, 10 s timeout, strips inbound X-Mage2React-* headers.

SEO Coverage

Every 2026 Google best practice is baked in (see full list in the SEO coverage section of SETUP.md). Highlights:

  • JSON-LD @graph — Organization, WebSite+SearchAction, BreadcrumbList, Product (with aggregateRating, priceValidUntil, itemCondition, brand), ItemList, CollectionPage, WebPage, SearchResultsPage, FAQPage, Article
  • Dynamic sitemap + image sitemap + OpenSearch XML + robots.txt with Host:
  • <link rel="prev"/next> for paged views, canonical strips ?page=1, ?sort, ?pageSize
  • Semantic HTML, one <h1> per page, <main>/<nav aria-label>/<article>
  • View Transitions API, system font stack, no external fetches on LCP path

Panth_React Magento Module

Lives at src/app/code/Panth/React/. Provides:

  • CORS plugin on Magento\GraphQl\Controller\GraphQl (allow list from admin config)
  • System config at Stores → Configuration → Panth → React Storefront
  • Health endpoint: GET /panthreact/health → {"ok":true,"version":"1.0.0"}
  • Branded SVG assets at view/frontend/web/images/{logo,favicon}.svg
  • Layout stub that empties the <content> container so direct hits to Magento's frontend don't leak broken Luma markup

Every one of the 38 Panth_<Name>React companions depends on this module via <sequence>.

Common Tasks

See SETUP.md for cache flush, reindex, static content deploy, production build.

Troubleshooting

Symptom Fix
Browser hangs ~5 s on first .local request macOS mDNS. First DNS lookup only; browser caches after. Use .test TLD to avoid entirely.
Site renders Luma theme instead of React Check Traefik priority — _web must be 1, _api 100.
"Proceed to Checkout" doesn't navigate Browser cached stale bundle. Hard-refresh (⇧R).
"Couldn't add to cart" on every product Stale cart cookie. Cart-store auto-recreates; hard-refresh.
Category page shows 0 products Top-level Luma categories aren't anchor. We aggregate descendants.
CSP blocks an image Add its origin to img-src in src/middleware.ts.
Panth widget renders nothing Check module is enabled + demo data present. Run the seed SQL from /tmp/panth-seed.sql during setup.

Compatibility

Requirement Supported
Magento Open Source 2.4.4, 2.4.5, 2.4.6, 2.4.7, 2.4.8
Adobe Commerce 2.4.4 – 2.4.8
PHP (Magento side) 8.1, 8.2, 8.3, 8.4
Node.js (frontend) 22 LTS
Browsers Evergreen (Chrome, Edge, Safari, Firefox)
Docker Docker Desktop, OrbStack, Colima, Rancher Desktop

Installation

1. Clone

git clone https://github.com/mage2sk/mage2react.git
cd mage2react

2. Shared dev infrastructure

You need a running dev_network with Traefik (TLS), MySQL 8, Redis 7, OpenSearch, Mailpit. See SETUP.md for a minimal example stack.

3. Configure

cp .env.example .env
# edit .env — set PROJECT_NAME, PROJECT_DOMAIN, DB creds, Redis DB numbers
echo "127.0.0.1 <your-domain>" | sudo tee -a /etc/hosts
mkcert -install && mkcert <your-domain>
# register certs in Traefik dynamic config, restart Traefik

4. Install Magento + Panth modules (one-time)

See SETUP.md for full bin/magento setup:install invocation with all flags. Once Magento is installed:

# Pull in all 38 Panth extensions (list in next section)
docker exec <project>_php composer require --update-no-dev --no-interaction $(grep 'mage2kishan/' composer-panth-requires.txt | xargs)
docker exec <project>_php bash -c 'bin/magento module:enable --all && bin/magento setup:upgrade'
docker exec <project>_php php bin/magento deploy:mode:set production

5. Boot

docker compose up -d

Open https://<your-domain>.

Configuration

After bin/magento module:enable Panth_React, visit Stores → Configuration → Panth → React Storefront:

Setting Default Description
Enable Yes Master toggle for the headless integration
Site URL https://<your-domain> Public origin of the Astro frontend
CORS Allowed Origins https://<your-domain> Newline-separated allow list for GraphQL CORS

Environment variables (.env):

Key Purpose
PROJECT_NAME Short lowercase identifier — used in container names, Traefik routers
PROJECT_DOMAIN Public-facing hostname
PHP_VERSION Magento PHP version (8.1 – 8.4)
DB_* Magento DB credentials
REDIS_*, OPENSEARCH_* Shared infra hostnames / ports
FRONTEND_PORT Astro dev port (default 4321)
MAGENTO_INTERNAL_HOST Container-to-container hostname for GraphQL

License

MIT — see LICENSE. Use it commercially, modify it, fork it, ship it.

Architecture

┌───────────────────── https://<your-domain> ─────────────────────┐
│ Traefik (TLS) │
│ │ │
│ ┌───────────────────────┼───────────────────────┐ │
│ │ priority 100: │ priority 1: │ │
│ │ /graphql, /rest, │ everything else │ │
│ │ /admin, /media, │ │ │
│ │ /static, /pub, │ │ │
│ │ /errors, /setup, │ │ │
│ │ /downloadable, │ │ │
│ │ /customer/section │ │ │
│ ▼ │ ▼ │
│ ┌───────────────────┐ │ ┌────────────────────┐ │
│ │ <project>_nginx │ │ │ <project>_frontend │ │
│ │ + php-fpm │ │ │ Astro 5 (Node) │ │
│ │ Magento 2.4.x │ │ │ React 19 + TW v4 │ │
│ └───────────────────┘ │ └────────────────────┘ │
│ │ │ │ │
│ └───── shared dev_network ─────────────────┘ │
│ │
│ shared MySQL 8.0 · Redis 7 · OpenSearch · Mailpit │
└─────────────────────────────────────────────────────────────────┘
  • Magento handles data (GraphQL, REST), admin panel, media, static assets.
  • Astro + React handles every storefront page, server-rendered, near-zero client JS.
  • Traefik splits traffic by URL prefix. Magento always wins on reserved paths.
  • Third-party Magento modules with frontend-only routes still work via Astro's catch-all proxy (src/pages/[...slug].astro).
  • Client → Magento mutations go through /api/graphql, a same-origin proxy that injects Authorization: Bearer <token> from the HttpOnly customer cookie.

Extending the Frontend

See SETUP.md for full extension patterns (new pages, GraphQL queries, React islands, hydration hints).

More Information
Module Category Headless
Best For Mid-Market

Need this customised?

Talk to Kishan directly — written quote, scope and timeline within 24 hours. No sales call.

WhatsApp

mage2react — Headless Magento 2 Storefront (Astro + React)

$0.00
Step up

Customers usually upgrade to