Who this is for#

You have Pionia Shop’s Moonlight API running on port 8000 and want a React or Vue storefront that calls product.list and customer.login — same origin in production, proxied /api during local dev.

What you will learn#

• When to run frontend:scaffold vs composer create-project … --react-ts
• How Vite dev (:5173) proxies to Pionia (:8000)
• Where built assets land (public/) and how SPA fallback works

Before you start#

How it works#

Pionia ships optional Vite scaffolding so Pionia Shop can have a React or Vue storefront calling product.list over the same origin in production.

flowchart LR
  Dev["Vite :5173"] -->|proxy /api| API["Pionia :8000"]
  API --> Moonlight["POST product.list"]
  Build["frontend:build"] --> Public["public/index.html + assets"]
  Browser[Production browser] --> Public
  Public --> Moonlight2["same-origin /api/v1/"]

Guide#

Quick start:

php pionia frontend:scaffold --framework=react-ts --yes
php pionia serve          # terminal 1 — API on :8000
php pionia frontend:dev   # terminal 2 — Vite on :5173

Common mistakes#

• Running only Vite without php pionia serve — API calls to /api fail with connection errors
• Hard-coding http://127.0.0.1:8000 in frontend fetch URLs — use relative /api/v1/ so production same-origin works
• Forgetting frontend:build before deploy — production serves from public/, not frontend/
• Missing [cors] for :5173 when testing auth headers from the browser

What’s next#