> **wix-vibe-headless** — chapter 20 of 20 in [wix/skills](https://skillsdocs.com/wix/skills).
>
> Book (all chapters, one file): https://skillsdocs.com/wix/skills.md
> Machine manifest: https://skillsdocs.com/wix/skills/.well-known/agent-skills/index.json
> Install the book: `npx skills add wix/skills`
> Upstream: https://github.com/wix/skills/blob/main/skills/wix-vibe-headless/SKILL.md @ `main`
> Raw bytes, no header: https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/
> Licence: MIT — https://spdx.org/licenses/MIT.html
>
> Bundled files (126), referenced from this skill's directory:
>   - `install/deploy.cjs` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/install/deploy.cjs
>   - `platforms/base44.md` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/platforms/base44.md
>   - `platforms/generic.md` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/platforms/generic.md
>   - `platforms/README.md` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/platforms/README.md
>   - `references/blog/app/components/PostCard.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/components/PostCard.jsx
>   - `references/blog/app/components/PostChips.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/components/PostChips.jsx
>   - `references/blog/app/components/PostGrid.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/components/PostGrid.jsx
>   - `references/blog/app/context/TaxonomyContext.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/context/TaxonomyContext.jsx
>   - `references/blog/app/hooks/usePostDetail.js` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/hooks/usePostDetail.js
>   - `references/blog/app/pages/Blog.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/pages/Blog.jsx
>   - `references/blog/app/pages/CategoryPage.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/pages/CategoryPage.jsx
>   - `references/blog/app/pages/PostDetail.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/pages/PostDetail.jsx
>   - `references/blog/app/pages/TagPage.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/pages/TagPage.jsx
>   - `references/blog/app/rest/wix-blog.js` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/app/rest/wix-blog.js
>   - `references/blog/INSTRUCTIONS.md` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/INSTRUCTIONS.md
>   - `references/blog/seed/seed-blog.js` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/seed/seed-blog.js
>   - `references/blog/seed/SEED.md` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/blog/seed/SEED.md
>   - `references/bookings/app/components/BookingForm.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/components/BookingForm.jsx
>   - `references/bookings/app/components/ServiceCard.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/components/ServiceCard.jsx
>   - `references/bookings/app/components/ServiceGrid.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/components/ServiceGrid.jsx
>   - `references/bookings/app/components/SlotPicker.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/components/SlotPicker.jsx
>   - `references/bookings/app/hooks/useServiceDetail.js` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/hooks/useServiceDetail.js
>   - `references/bookings/app/hooks/useServices.js` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/hooks/useServices.js
>   - `references/bookings/app/pages/ServiceDetail.jsx` — https://raw.githubusercontent.com/wix/skills/main/skills/wix-vibe-headless/references/bookings/app/pages/ServiceDetail.jsx
>   - …and 102 more, listed in https://skillsdocs.com/api/v1/books/wix/skills/skills/wix-vibe-headless
>
> Content © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: wix-vibe-headless
description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), CMS / Wix Data (list, detail, filter, forms, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
---

# Wix Vibe Headless — client-only REST connectors

Wire an existing front end to a live Wix site **from the browser**, over the site's public
`WIX_CLIENT_ID`, using hand-rolled REST — **no `@wix/sdk`, no backend, no build step, no
dependencies**. One skill, one shared transport, and a copy-as-is REST layer per Wix
business solution. Everything is **read-only over the owner's content**: render live Wix
data or an honest empty state — **never mock, never provision, never invent** products,
posts, events, menus, plans, reviews, or counts.

## When to use this skill

- The user has (or is building) a front end — a vibe-coded app, plain HTML/JSX, a Vite/React
  project, a design-tool export — and wants it to show **live data from their existing Wix
  site** and complete real purchases/bookings, all from the client.
- They hand you a **public `WIX_CLIENT_ID`** and ask to "connect this to my Wix store /
  blog / bookings / events / …".
- They want to replace placeholder/mock data with real Wix content, or add a cart, checkout,
  booking, RSVP, ticketing, reservation, form, or subscribe flow over an app they already have.

## When NOT to use this skill

| Scenario | Use instead |
|---|---|
| Build a **new** Wix site end-to-end from one prompt (discovery → design → build → host) | `wix-headless` |
| The project should use the **Wix SDK** (`@wix/sdk`) and/or the **Wix CLI**, or be **hosted on Wix** | `wix-headless` |
| Manage/configure the site via REST (install apps, seed catalogs, set up business solutions) | `wix-manage` |
| Build a Wix **app extension** (dashboard page, widget, backend, plugin) | `wix-app` |

This skill is the deliberately **client-only, REST-only** path. It is independent from
`wix-headless` (which is SDK + CLI + hosting) — do not mix the two in one project.

## The shared model (applies to every vertical)

- **Auth = one public client id.** `WIX_CLIENT_ID` is a **buyer/visitor-facing** credential —
  it only mints anonymous visitor tokens. It is **not a secret**; hardcoding and committing it
  is fine. The user provides it (their vibe/host platform surfaces a copyable prompt with the
  id filled in). Paste it into `wix-config.js` in place of the `<YOUR-CLIENT-ID>` placeholder.
- **Money/price fields are objects, never scalars.** Every price/amount a Wix API returns —
  Stores `price.actualPrice`, Bookings service `payment.fixed.price`, Events ticket
  `registration.tickets.lowestPrice`, and the rest — has the shape `{ value, currency,
  formattedValue }`. Render **`formattedValue`** (it already includes the currency symbol), or
  fall back to building from `value` + `currency`. **Never** drop the object straight into the UI
  or treat it as a number/string — that renders `[object Object]` or a bare unformatted number.
- **Visitor token = identity.** `wix-client.js` mints an anonymous visitor token, persists the
  **refresh token to `localStorage`**, and refreshes on expiry. That token IS the identity of
  the cart / reservation / member session — **never re-mint anonymously per load** or the cart
  silently empties.
- **Member login swaps the token set on the same client.** The **members** vertical is *custom*
  login — the front owns its login UI; the member is **never redirected to a Wix-hosted login page**.
  On success it writes the member's tokens into the *same* store the visitor token used
  (`setSessionTokens`), so **every subsequent `wixApiRequest` runs as the member** and the cart/session
  carries over. "My …" surfaces (plans, orders, bookings, registrations) light up only once logged in.
- **⚠️ Once you're building on Wix, keep it on Wix — auth, member data, and other business features
  too.** If you're wiring a Wix storefront/blog/etc. over `WIX_CLIENT_ID`, prefer Wix for the *rest*
  of the app as well, rather than reaching for a host platform's own backend or login. **Especially
  for auth:** when the user wants members, log them in as a **Wix member** (`members` vertical) — don't
  bolt on the host platform's auth. Likewise, member-generated content (likes, reviews, submissions,
  "my …" lists) goes in a **Wix CMS collection** (`cms` vertical), not a host database.
  - **The split-brain trap:** the most common failure is mixing the two — e.g. storing "likes" in the
    host's DB while identifying the member from the Wix session (or logging in with Wix members but
    keying data on a host user id). The two identities never match, ownership filters silently return
    nothing (a like vanishes on refresh), and the data never sits with the rest of the Wix content.
  - **Rule of thumb:** one store and one identity per feature. For a Wix-backed feature that's the Wix
    member + the Wix collection, with ownership on Wix's server-stamped `_owner` (never a hand-stored
    or host-supplied member id). Using a host backend for genuinely host-only data is fine — just
    never straddle a single feature across both.
- **Never mock, never provision.** These scaffolds are read-only over the owner's content. The
  owner adds products/posts/services/events/menus/plans in the **Wix dashboard**. If a
  collection is empty, show the empty state — never fabricate data, reviews, ratings, or counts.
- **Purchases go through Wix.** Checkout/ticketing/plan purchase always complete via the Wix
  redirect-session / Wix-hosted form — **never hand-build a `/checkout` or purchase URL**.
- **Fail loudly.** The helpers throw on out-of-stock, empty carts, unbookable slots, expired
  holds, and payment-still-owed. A green path means it really worked — don't swallow the error.
- **Copy the shipped helpers as-is — don't rewrite their internals.** Wire your UI to the *exported*
  functions; don't "refactor" or reimplement the helper bodies. Several Wix request shapes are exact
  and easy to break (the members `createRedirectSession` body is the classic trap — a rewritten
  version returns 400 and login dies). Extend by *calling* the exports or adding a new
  `wixApiRequest` call for a genuine gap — never by editing the shipped ones.
- **Beyond the snippets, look it up — never guess.** The templates and the shipped
  `references/<vertical>/` helpers are the implementation — build from them first. When you hit a
  genuine gap (a field, an endpoint, or an error the snippets don't cover), extend the client with
  `wixApiRequest` — confirming the exact endpoint, method, and body first. **For that iteration and
  troubleshooting** — finding the right endpoint, reading a method's request/response schema, or
  diagnosing an API error — fall back to the **`wix-docs`** skill (`../wix-docs/SKILL.md` when
  co-installed): it covers `curl` doc-search, reading pages, and structured API-spec queries.
  Reference index: https://dev.wix.com/docs/api-reference.md
- **Provide the user with deep links to the Wix dashboard**: In many cases, the user will need to modify the default vertical data in the Wix dashboard. Always provide the user with these links. The relevant information for each vertical's links is in its `INSTRUCTIONS.md` file.

## How this skill is structured

`<SKILL_ROOT>` is this file's directory (strip `/SKILL.md`). Each vertical ships a **complete UI
client as files** under `references/<vertical>/app/` — `components/`, `pages/`,
`hooks/`/`context/`, and its REST helpers in `app/rest/` — plus the **shared transport** in
`references/shared/app/` (`app/rest/wix-client.js` + `wix-config.js`, identical for every vertical).
Set `WIX_CLIENT_ID` (and `WIX_METASITE_ID`) in `wix-config.js`. Deploying `references/<vertical>/app/`
and `references/shared/app/` into the app's `src/` puts every file in place — the helpers all land in
`src/rest/`, so their relative imports resolve.

**Where these files live in the app, and how they get there** (pre-installed at setup, or copied
in) **is your platform's call — follow your platform instructions for that.**

Each vertical's `INSTRUCTIONS.md` is the full playbook for that solution: when to use it,
prerequisites, the exported API, how to wire it, the hard rules, and a verification checklist.
**Open the relevant `INSTRUCTIONS.md` before wiring** — the shapes and gotchas live there.

## Routing — pick the vertical(s) from the request

Load the vertical(s) the user's app needs; a project may combine several (e.g. a restaurant
with a blog, or a store with pricing plans).

Each vertical's UI + helpers ship in `references/<vertical>/app/`; copy that dir plus
`references/shared/app/` into the app's `src/` (base44 does this at install via `deploy.cjs`).

| The user wants… | Vertical | Read |
|---|---|---|
| Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` |
| Appointments: services, time slots, booking, checkout | **bookings** | `references/bookings/INSTRUCTIONS.md` |
| Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` |
| Events: browse, event page, RSVP, ticketing | **events** | `references/events/INSTRUCTIONS.md` |
| Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` |
| Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` |
| CMS content: list/detail, filter/search, forms, data CRUD | **cms** | `references/cms/INSTRUCTIONS.md` |
| Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
| Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` |

### When the request doesn't name a Wix Business Solution — ask, or check the site

Don't infer which Wix Business Solution to build (stores, bookings, blog, events, portfolio,
restaurants, CMS, pricing plans, members, etc..) from a vague brief. **Ask the user** one short
question — what do they offer (products? appointments? posts? events?) — or **check what the
site actually has**: call a cheap read from each likely solution's helper (`queryProducts`,
`queryServices`, `queryPosts`, `queryEvents`, …) — authenticated with a visitor token minted
from the `WIX_CLIENT_ID`, or with an admin token if you have one — and build for the solutions
that return real content. A `428` "app not installed" (blog: `401`) means
that solution isn't on the site; sample-looking content ("Sample product 3") proves the app is
installed, not what the business is about. Never default to store/bookings on silence.

## The run

1. **Get `WIX_CLIENT_ID`.** It comes from the user (the handoff prompt from their Wix/vibe
   platform carries it). If it's missing, ask for it before wiring — nothing works without it.
2. **Pick the vertical(s)** from the routing table — and when the request doesn't name any,
   **ask or check the site** (see above) instead of guessing. Open each picked vertical's
   `INSTRUCTIONS.md`.
3. **Ensure the vertical's files are in place** — copy `references/<vertical>/app/` and
   `references/shared/app/` into the app's `src/`, and set `WIX_CLIENT_ID` in `wix-config.js`. (Where
   and how they get there is your platform's call — see its instructions.)
4. **Wire the shipped client** following the vertical's INSTRUCTIONS: the components are themed by
   base44's design tokens (`src/index.css` — shadcn palette, already set by the design phase), so
   there's no re-skin step; just wire routes + header/footer through the Layout. The UI ships as
   files — you compose the home page and wire it, you don't rebuild the client.
5. **Verify** against the vertical's checklist before declaring done: token persists across
   reload, live data renders (or a real empty state), and purchases go through the Wix redirect.

> Some flows need Wix-side setup the user completes later (payments connected, the deployed
> domain allow-listed on the OAuth client for hosted-checkout return, collection permissions).
> Those are out of scope here — if a call fails for that reason, flag it and continue; don't
> fall back to mock data.