/wix-vibe-headless

Wix Bookings — ready-made client

The bookings client is shipped as real files, not snippets to regenerate. It's a complete service catalog + detail page + slot picker + booking flow (create booking → hosted checkout), styled with your app's design tokens (base44's src/index.css — the shadcn palette the design phase already set). Copy it into the app and wire the routes — you generate almost none of the booking code (the { services } / { slots } destructuring, the local wall-clock date args, the null-slot re-validate guard, the participant cap, the eCom redirect-session all ship and are correct).

Talks to Wix directly over the public WIX_CLIENT_ID (anonymous visitor tokens). Never mock services or slots; never hand-build a /checkout URL — the shipped flow creates the booking through the API and completes it via the eCom redirect-session.

Prerequisites

• The site's Wix Bookings setup is the read/book target. It's installed and seeded separately (see Seeding below), in parallel with this build — so it may have no services at build time; the client renders the shipped empty state until services (and staff/working hours, so slots are bookable) land. This client is read-only over services — it does not provision them.
• The public headless WIX_CLIENT_ID from your prompt (buyer-facing, safe to hardcode/commit).
• For paid services, the site must accept payments and the deployed app domain must be allow-listed on the OAuth client for the hosted checkout to return. Those are separate Wix setup flows the user completes later — out of scope here; if checkout return fails before that, it's expected, flag it and continue.

STEP 1 — The client is already in src/

The install step (base44.md STEP 1) deployed the whole bookings UI client + REST scaffolds into src/ (imports use the @/ alias → src/). Here's every file and what it is — this is your map, so you don't need to open them:

They're already in place — go straight to theming + wiring, nothing to verify first. Don't read_file the shipped page/component/hook source to inspect it — the table above says what each is, and every field shape you need is in the snippets below. Read a shipped file's source only on a real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the end). (Files missing? the install's deploy result lists what it wrote; re-run install, or copy references/bookings/app/ → src/.)

Their Link/useParams imports come from @/lib/nav, so the same sources run on either template. That adapter is installed at src/lib/nav.js with the rest of the deployed tree — use the file that is there, and on TanStack check it first (which template?). Import from @/lib/nav in the pages you write too, and they stay portable the same way.

STEP 2 — Theme

Use the existing Base44 theme in src/index.css so your pages and the shipped components share the same colors and typography.

STEP 3 — Wire routes (surgical find_replace on src/App.jsx, never a rewrite)

The template decides this step, and src/routes/__root.jsx is the question to ask first. Present → TanStack Start, which mounts these pages as route files at the end of this step; absent → React Router, which the wiring below is written for. Ask in that order: an src/App.jsx can exist on a TanStack app because an agent created one, and __root.jsx is never there by mistake. The installed src/lib/nav.js defaults to the React Router adapter, so on TanStack swap it: both patterns.

Import Link, useParams and friends from @/lib/nav in the pages you write too — same names as the router exports, and nothing you write is pinned to one template.

No file reads needed to wire this. Every shipped page and WixManageBanner is a default export that takes no props — wire them exactly as the snippet shows; nothing in those files needs looking up. App.jsx carries required platform auth scaffolding (AuthProvider/useAuth) — edit it in, don't replace it. Bookings needs no cross-page provider (there's no cart — each booking completes on its own detail page), so there's nothing to wrap the tree in.

• Put your header + footer in a Layout that renders <Outlet/> between them, and nest every route under one pathless <Route element={<Layout/>}>. Your brand chrome then wraps every page — including the shipped Services / ServiceDetail — so you never edit the shipped pages to add a header/footer (they render inside <Outlet/> as-is).
• Pin the top chrome as one fixed block. Put <WixManageBanner/> (shipped, preview-only) above your <Header/> inside a single position:fixed top region — the header itself is plain in-flow markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad the content by the region's ResizeObserver-measured height so it clears the chrome and self-corrects when the banner is dismissed.
• Routes under the Layout: /services → Services, /service/:serviceId → ServiceDetail (both shipped, as-is). You add / → your own Home page.

import { useRef, useState, useEffect } from "react";
import { Routes, Route, Outlet } from "react-router-dom";
import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
import Services from "@/pages/Services";               // shipped · default export, no props
import ServiceDetail from "@/pages/ServiceDetail";     // shipped · default export, no props
import Home from "@/pages/Home";           // YOU build
import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
import Footer from "@/components/Footer";   // YOU build

function Layout() {
  const topRef = useRef(null);
  const [offset, setOffset] = useState(0);
  useEffect(() => {                                  // measure the fixed region → pad content below it
    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
    if (topRef.current) ro.observe(topRef.current);
    return () => ro.disconnect();
  }, []);
  return (<>
    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
      <WixManageBanner />                    {/* null on the published site / when dismissed */}
      <Header />                             {/* your brand header, in-flow inside this fixed block */}
    </div>
    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
      <Outlet />                             {/* shipped Services/ServiceDetail render here, untouched */}
      <Footer />
    </div>
  </>);
}

<Routes>
  <Route element={<Layout />}>                                       {/* chrome wraps all */}
    <Route path="/" element={<Home />} />                            {/* yours */}
    <Route path="/services" element={<Services />} />                {/* shipped, as-is */}
    <Route path="/service/:serviceId" element={<ServiceDetail />} /> {/* shipped, as-is */}
  </Route>
</Routes>

TanStack Start template — the same pages, mounted as files

Chrome (header, footer, the fixed banner region described above) goes in src/routes/__root.jsx around its <Outlet/>, and any provider this vertical asks for wraps that <Outlet/> once. Each route is a two-line file; shipped pages stay in src/pages/ untouched.

// src/routes/services.jsx
import { createFileRoute } from "@tanstack/react-router";
import Services from "@/pages/Services";

export const Route = createFileRoute("/services")({ component: Services });

Path params are $name in both the filename and the route path; useParams() from @/lib/nav reads them unchanged. Full pattern, including ssr: false for per-user routes: ../_shared/routing.md.

What you build (not shipped)

The home / landing page, the Header and a Footer — the two you drop into the Layout (STEP 3) so they wrap every route — plus the overall brand story, styled with the same base44 tokens/classes. Compose the shipped pieces — a "featured services" strip is just queryServices + the shipped ServiceGrid; the nav is a link to /services:

import { useState, useEffect } from "react";
import { Link } from "react-router-dom";
import { queryServices } from "@/rest/wix-bookings-services";
import ServiceGrid from "@/components/ServiceGrid";

// Responsive header: choose ONE branch with a state flag (copy this pattern). Do NOT render a
// desktop nav AND a mobile nav toggled by Tailwind `hidden md:flex` / `md:hidden`: these navs are
// inline-styled, and an inline `display` beats a Tailwind class, so `hidden` never applies — BOTH
// branches render. One branch = one nav.
export function Header() {
  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
  useEffect(() => {
    const onResize = () => setMobile(window.innerWidth < 768);
    window.addEventListener("resize", onResize);            // keep it reactive to viewport changes
    return () => window.removeEventListener("resize", onResize);
  }, []);
  return (
    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
      {/* brand/logo */}
      {mobile ? <YourMenu /> : <Link to="/services">Services</Link>}
    </nav>
  );
}
export function Featured() {                                // on your home page
  const [services, setServices] = useState([]);
  // NB: queryServices returns { services, total, nextOffset } — destructure the array.
  useEffect(() => { queryServices({ limit: 6 }).then(({ services }) => setServices(services)); }, []);
  return <ServiceGrid services={services} empty="Services coming soon." />;
}

Everything reads base44's design tokens (index.css), so your home/nav match the shipped pages automatically.

Editing a component and the change doesn't show? It's the preview, not your code. The dev preview can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do a fresh full navigate/reload of the preview and re-check — don't keep rewriting correct code against a stale render.

Using the client from your own UI

The two shipped hooks are the whole flow. If you build a custom surface, drive it the same way:

Migrating from Cart V1 / Checkout V1? These helpers are V2-only — see the migration guide for the before/after.

// LIST — every list helper returns an OBJECT, not a bare array. Destructure it:
const { services, total, nextOffset } = await queryServices({ limit: 24 });   // total 0 → empty state
if ((await countServices()) === 0) { /* show the empty state — never invent services */ }

// DETAIL — getService(id) is keyed off the route param; returns null on a miss (not-found, never invent):
const service = await getService(serviceId);

// FACTS (price / duration / capacity / where / reschedule note) — lib/serviceFacts.js branches on
// payment.rateType and on APPOINTMENT-vs-CLASS for you. Reading payment.fixed.price yourself renders
// NOTHING for a VARIED or NO_FEE service, and duration is empty on a class:
const price = servicePriceLabel(service);      // "€95.00" · "From €85.00" · "Free" · "" for CUSTOM
const minutes = serviceDuration(service);      // 60 for an appointment; null for a class/course
const where = serviceLocationLabel(service);   // from payment.options — service.locations has no name

// IMAGE — the primary image is media.mainMedia; resolve through mediaUrl (Wix media can be a bare
// handle, not a full URL). Fall back to the gallery/cover:
const img = mediaUrl(service.media?.mainMedia?.image ?? service.media?.items?.[0]?.image ?? service.media?.coverMedia?.image);

// SLOTS — listSlotsForService routes by service.type and returns { slots, nextCursor }; iterate .slots.
// Dates are LOCAL wall-clock "YYYY-MM-DDThh:mm:ss" (NO zone / Z). The LIST call takes
// fromLocalDate/toLocalDate — the single-slot re-validate (getAvailableSlot) takes
// localStartDate/localEndDate. They are NOT interchangeable.
// It also returns `timeZone` — the zone those localStartDate strings are in. Label the picker with
// that value rather than a locally guessed zone, so the times and the label can't disagree.
const { slots, nextCursor, timeZone } = await listSlotsForService(service, { fromLocalDate, toLocalDate });

// BOOK — re-validate the picked slot (getAvailableSlot returns the slot or NULL — guard it), then
// book + check out and redirect. Participants: cap at
// service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking (commonly 1 → no selector);
// never use slot.remainingCapacity as the per-buyer limit.
const fresh = await getAvailableSlot(service.id, { localStartDate, localEndDate });
if (!fresh) { /* "that time was just taken — pick another" */ }
const { checkoutUrl } = await bookAndCheckout(fresh, { email, firstName, lastName, phone }, { totalParticipants });
window.location.href = checkoutUrl;   // hosted checkout; on return the booking is CONFIRMED/PENDING

Extending the client

The shipped flow covers APPOINTMENT and CLASS services (listSlotsForService routes by service.type). For anything beyond that, add a helper on wixApiRequest, looking the endpoint up using the documentation skill available in your environment first (never guess):

• COURSE enrollment — a course is enrolled as a whole, not per session; listEventTimeSlots returns no slots for it, so the slot-picker flow doesn't apply (course-specific flow).
• Service variants / participants (duration- or person-based pricing), add-ons, and custom booking form fields (render service.form.id).
• Member login + a "my bookings" view → the members vertical (references/members/INSTRUCTIONS.md): booking works anonymously, but signing a member in lets them see their own appointments.

Fallback only — when you hit an error or need something not shown here: read the relevant shipped file under src/, or look it up via the documentation skill available in your environment. Each helper in wix-bookings-services.js / wix-bookings-checkout.js links its own reference page inline; these are the areas they sit in:

• Bookings (services, categories, bookings): https://dev.wix.com/docs/api-reference/business-solutions/bookings.md
• Availability time slots: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots.md
• eCommerce checkout (paid bookings): https://dev.wix.com/docs/api-reference/business-solutions/e-commerce.md
• Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md

Rentals — the same client, one extra step

Wix Rentals has no APIs of its own. A rental is a Bookings service with rentals-specific field values, so this whole client works on it: the catalog read, the booking form, and the createBooking → cart → checkout chain are all unchanged. rest/wix-bookings-rentals.js and hooks/useRentalDuration.js carry the only differences.

What tells a rental apart — the DATA, never the brief. A service carries either a fixed session length or a duration RANGE the customer picks within; the two are mutually exclusive:

import { isRental, rentalDuration, rentalRateLabel } from "@/rest/wix-bookings-rentals";
isRental(service)   // true only when schedule.availabilityConstraints.durationRange is present

A 60-minute yoga class and a 60-minute massage are not rentals even though a massage is type: "APPOINTMENT" exactly like a rental is. Never branch on the service's name, its category, or what the brief called it.

The extra step. An ordinary service is one choice (a slot). A rental is two: pick a START, then pick HOW LONG — and the price follows the length.

const detail = useServiceDetail(serviceId);                        // service + start times
const rental = useRentalDuration(detail.service, detail.selectedSlot, detail.timeZone);

<SlotPicker … />                                                   {/* pick a start, as ever */}
{rental.isRental && <RentalDurationPicker rental={rental} />}      {/* then pick a length */}

Book with rental.endDate as the slot's localEndDate; everything else in the booking call is identical.

Hard rules on top of the ones below:

• Filter every catalog read by appId. queryRentals() does it. On a site with both apps an unfiltered queryServices returns haircuts next to meeting rooms.
• Never compute the total yourself. A rental is charged as a rate, hourly at per-minute granularity — 90 minutes of a $10/hour room is $15. useRentalDuration prices the chosen length on the server; multiplying the displayed rate disagrees with checkout.
• Show the total before the customer commits. A rate alone is not a price.
• One unit type per service. A room rented by the hour and by the day is two services.

Hard rules

• Header/footer live in a Layout around <Outlet/> (STEP 3) — never edit the shipped Services/ServiceDetail to add chrome.
• The Layout's fixed top region owns positioning: <WixManageBanner/> above <Header/>; your Header is plain in-flow markup (not position:fixed).
• Send availability/booking dates as local "YYYY-MM-DDThh:mm:ss" strings + a timeZone — never UTC Z timestamps to the slot APIs.
• Re-validate the slot with getAvailableSlot() before booking; guard the null — slots get taken.
• Cap participants at maxParticipantsPerBooking (no selector when 1); never offer a fixed range and never use slot capacity as the per-buyer limit.
• Book only through the shipped flow (bookAndCheckout / createBooking→checkoutBooking) and redirect to the returned URL — never a hand-built /checkout or calendar URL.
• Render live Wix data or the shipped empty state — never mock services, slots, or availability, and never invent reviews, ratings, staff, or testimonials.

Point the user to their dashboard

Provide deep links so the owner can manage bookings content (substitute the site's metaSiteId):

• Booking Services — https://manage.wix.com/dashboard/{metaSiteId}/bookings/services (add services and service categories)
• Staff — https://manage.wix.com/dashboard/{metaSiteId}/bookings/staff (add staff and set working hours, so slots are actually bookable)

Seeding

Seed the services per seed/SEED.md (the build-time setup module) — separate from this client build; run in parallel.

Verify (before declaring done)

• Client files copied into src/; WIX_CLIENT_ID set (not the placeholder).
• Opened /services and a service detail page (not just the home page) and confirmed the shipped cards render themed (surface, text, brand color) with images.
• Layout (fixed <WixManageBanner/> + <Header/> region, then <Outlet/> + Footer) wraps all routes; shipped Services/ServiceDetail untouched; content clears the fixed chrome.
• Visitor token persists across reload (same visitor identity across reloads).
• queryServices() renders live services; empty catalog shows the shipped empty state (no mock services).
• Slot picker shows real bookable slots; the slot is re-validated with getAvailableSlot() right before booking.
• Participant selector capped by maxParticipantsPerBooking (hidden when 1).
• Booking redirects to the hosted checkout URL the client returns; on return the booking is CONFIRMED/PENDING.
• No mock services, slots, or availability anywhere.