/wix-headless

SDK-integration handoff

This is the last step — reach it only after Setup and Seed have run. The guide below is filled from the seeded map (created IDs), which exists only because Seed executed; if you're here without having installed the apps and seeded content, go back and do that first. The guide describes the backend the earlier steps built.

The skill returns this document describing how to call Wix from the frontend, then exits. The host agent — which owns the frontend, the framework, and the build — does the wiring. We describe what to use and link to the live Wix SDK docs for the API shapes; the host decides where they go.

Link to the docs for API shapes; don't inline examples. The Wix SDK docs are versioned and complete; hand-written snippets under-specify the hard parts (rich-content rendering, package versions, types) and lead the host to build against a wrong shape. The handoff supplies what the docs can't: the seeded IDs, the clientId source, and the package set. The package set is the inlined map in §3 — the SDK doc .md pages don't surface the @wix/* import string to navigation, so the map is the source of truth for which packages; the inline recipe each row points to is the source of truth for how to call them (current API shape + version).

The linked docs are the source of truth for current API shapes and versions — read them for the integration. Existing code (in this or any other project) is not a substitute: it may target a different SDK version and silently mislead.

Emit the document as the skill's final message (a Markdown block the host can act on or save). Fill it from the run's verticals[], the seeded map, the OAuth app's public clientId, and — for each loaded capability — its Required site features and Implementation checklist from references/CAPABILITIES.md (§6). Include only the loaded capabilities. The guide isn't just "here are the IDs and packages"; it's the spec for a complete site, so the host builds real features (author, comments, dates…) rather than a bare data dump.

What the document contains

1 · Packages to install

The always-on package is @wix/sdk (provides createClient + OAuthStrategy). Add the union of the loaded capabilities' runtime packages from the map in §3. Runtime packages only (no scaffold/build deps). For install details and current versions, link: https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/install-sdk-packages.md.

2 · Client setup (and the clientId source)

With a manual client the frontend authenticates as an anonymous visitor via OAuthStrategy, with clientId = the OAuth app's public client id. This is the model for host-owned frontends (this guide is emitted) and the skill's non-Astro path (references/non-astro.md). Managed-Astro is the exception — it auto-authenticates with no client at all (references/astro.md); skip this section's clientId wiring there. Two facts hold whenever a client is used: the clientId is not secret (it's the public OAuth id), and the client_secret never reaches the frontend. Two type-independent steps:

1. Obtain the clientId via the provided authentication mechanism — see <TYPE_DIR>/AUTHENTICATION.md (each type names where the public id comes from; don't re-mint or re-fetch it if the type already provides it).
2. Get the clientId into the client bundle — this depends on who owns the frontend, not on the project type:
   • The host owns the frontend (this guide is emitted — backend-only: self-managed, stripe, or managed backend-only) → the host exposes the value to client code via its framework's public-env convention (NEXT_PUBLIC_*, VITE_*, PUBLIC_*, …).
   • The skill owns the frontend (this guide is applied — managed create/connect) → how the frontend authenticates is framework-specific, so follow the frontend reference, not this bullet. On Astro (the default) authentication is automatic — there is no client and no clientId to wire (references/astro.md). On a non-Astro frontend you build a manual client (references/non-astro.md): wire the clientId in via the framework's public-env convention if one exists, otherwise inline the public id into the client code/bundle.

For the current createClient + auth-strategy shape, link:

• https://dev.wix.com/docs/sdk/articles/set-up-a-client.md
• https://dev.wix.com/docs/sdk/articles/set-up-a-client/authorization-strategies.md

Confirm the clientId reached the built bundle before deploying. Public-env wiring fails silently — a mis-wired public var inlines as undefined, and then every visitor token call from the live site 400s with no other clue. After the production build, verify the actual clientId value is present in the built output (check that the value resolves — not merely that the variable name appears somewhere). Doing this pre-deploy stops it from being mistaken for an origin/CORS problem afterward.

3 · Per-capability packages + API docs (package from the map; recipe for shapes)

For each loaded capability, give the host the package(s) from the map below and point it at the capability's inline recipe (references/inline-recipes/how-to-code-*.md) — the pinned API shape, methods, version, and failure modes live there; don't re-summarize them here. The map is the source of truth for which packages; the recipe is the source of truth for how to call them. The recipes are local — Read them with the file tool, don't curl.

Before implementing a capability, Read the local recipe linked in its row.

Cross-cutting packages (CAPABILITIES.md § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If coupons were seeded, add @wix/marketing. The eCommerce checkout packages (@wix/ecom, @wix/redirects) are already folded into the stores row above — include them once when any purchase-flow vertical is present.

members (cross-cutting — add when the site has login / account / gated content, or whenever pricing-plans is loaded). Package: @wix/members (current member / profile via getCurrentMember — not the dev-preview @wix/site-members); auth is the OAuthStrategy/session methods on the always-on @wix/sdk. The API shape lives in the axis recipe — Read the one that matches the frontend, not both: how-to-code-members-astro.md (Astro: built-in /api/auth/login + /api/auth/logout, no client) or how-to-code-members-non-astro.md (non-Astro: manual OAuthStrategy handshake). Both are the Wix-hosted login page (the default). Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields, Read how-to-code-members-custom-login.md instead — the surface is chosen by intent, not by project type.

Why a map and not navigation: the SDK doc .md pages don't expose the @wix/* import string to a reader (it's only in the page's interactive UI), so the package column is inlined here as the source of truth. If a package name ever drifts, reconcile it against the SDK install article (§1) — not by guessing from the module URL. The linked pages remain authoritative for the API itself.

4 · Seeded schema (what the host binds to — names + field keys, not content IDs)

The host binds to schema, not to a frozen list of content IDs. Content is discovered live: every listing is a query-all (queryProducts/queryPosts/queryEvents/queryServices/queryPlans/items.query/listMenus…), every detail page resolves a [slug]/[...slug] route from the URL at request time (the frontend is SSR — no getStaticPaths), and category/nav is a live query. So the frontend never needs the seeded per-item id/slug arrays — and not carrying them is deliberate: an id the host was never handed is an id it can't hardcode, so content the owner adds later in the backoffice flows through by construction (see §6).

Carry only the structural carve-outs the coding step genuinely reads — the collection/form names and keys you must know to query and bind, which do not change when an owner adds a row:

• cms: collectionId + field keys per collection
• forms: formId + each form's field target keys (the submission keys the frontend binds name = target). Field set, labels, options, and validation (required, format, length/pattern) are read live from the schema (how-to-code-forms.md).

Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public clientId are needed too, but they're identical for every site, not seed output; they're in §2/§3.)

5 · Integration notes (headless-auth specifics the per-module docs won't frame)

• Restaurants online ordering has real-world go-live preconditions the code can't satisfy — surface them to the owner. For a working ordering flow the site needs: (1) a business location with a real address (the skill sets this in setup-restaurant-orders.md STEP 0 — but if the brief gave no address, a placeholder was used and the owner MUST replace it, or checkout stays "testing only"); (2) a premium plan; (3) a configured payment method. State these plainly in the guide/summary — the site is not "done" for real orders until the owner completes them. (The same premium+payment note applies to any eCommerce checkout, e.g. stores.)
• The visitor token has no per-user identity → seeded CMS collections are public/shared across all visitors (not per-user, not cross-device). Per-user storage needs member auth.
• Frontend CMS access is read; visitor writes go through Forms submissions.
• Blog comments are member-gated — read public, write authenticated. Querying/rendering comments is public, so list them server-side in SSR. Submitting needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (src/pages/api/*.ts) that calls createComment with the request session; if the caller isn't a member, redirect to the built-in /api/auth/login?returnUrl=…. Do not build the comment form as a client island — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post referenceId, Blog appDefId, author lookup via post.memberId) are in how-to-code-a-blog.md.
• Member auth is one mechanism split on the frontend axis (the §3 members note routes to the right recipe), and orthogonal to elevation. Sign-up and log-in are the same flow (the Wix login page logs in or registers); log-out is its inverse. Two layers stay separate: identity (logged-in vs not — no app install) vs profile (name/photo/roles — needs the Wix Members Area app installed, SETUP.md). pricing-plans is a hard dependency: subscribing requires a logged-in member; for the other verticals, member login is a soft add-on for their "my …" surfaces only. A member reading their own data (own orders/bookings/subscriptions, plan-gated content) uses the member token with NO auth.elevate — elevation is the separate admin/permission axis (site-wide reads, server-side only), not something member features need.
• Gating is a LIVE signal, never a hardcoded id list. Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read at request time — a queryable flag carried on the content (a members-only blog category/tag or a boolean CMS field) and live coverage/eligibility (Cart V2's currentCartV2.calculateCurrentCart() → summary.paymentSummary.memberships, or the member's active-order planIds matched against live Benefit-Program coverage). Never gate on a frozen set of "premium" slugs/ids or a seed-time plan→service map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See how-to-code-a-blog.md (member features) and how-to-code-pricing-plans.md (coverage read).

6 · What a complete site must include (per loaded capability)

For each loaded capability, carry its Required site features and Implementation checklist from references/CAPABILITIES.md into the guide — in plain product language, lightly tailored to what was seeded. This is the build spec, not optional polish: the host should build every required feature and cover every checklist item. For example, a blog must show the author (name + photo), the publish date and reading time, the cover image, and the full formatted content (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.

• State them as the what (product behaviour), not the how (no component code, no API calls) — the host owns the build.
• When a loaded vertical ships an experience overlay (references/inline-recipes/experience-<vertical>.md; today experience-store.md), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general DESIGN.md/CONTENT.md.
• If a required feature depends on backend support that Seed enabled (e.g., comments), note it's available so the host wires it. If Seed could not enable it, say so plainly rather than implying the site is complete.
• When pricing-plans is loaded, login / account / gated content is a required feature, not optional polish — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching how-to-code-members-*.md recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated enhancement — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
• Curation / hero / nav must come from a LIVE query, never a pinned slug/id. A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (queryEvents filtered to UPCOMING/STARTED, sorted by start date), "newest" (queryPosts), queryCategories, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go stale/past. Even a single-item site (one event, one product) must drive its homepage from the listing query, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.
• State the residual limitation honestly — don't over-claim a "self-maintaining" site. New content flows through live with no code change and no re-publish: a product, post, event, service, plan, menu item, or category the owner adds in the backoffice appears via the live queries above. Forms are schema-driven, so an added/removed/relabelled form field of a supported input type (text/email/phone/url/textarea/dropdown) — or a tightened validation rule (required, minLength/maxLength/pattern, format) — also reflects live with no code change (how-to-code-forms.md). But new content types / collections / ticket-tier semantics, and a form field of a novel type the renderer doesn't handle yet, require a code change — the frontend renders an authored schema, so a new CMS field, a new collection, a novel ticket structure, or an unsupported form field type won't render until coded. Say this plainly in the guide rather than implying the site maintains itself beyond that.
• Before finishing, verify nothing is pinned. Confirm no route, listing, gate, or nav is filtered against a seed-time id/slug array held in code — every such filter must key off a stable id used in a live query (a categoryId from queryCategories, a slug from the URL/query result), not a frozen membership list. A pinned array is the one way owner-added content silently fails to appear.

How to navigate the Wix docs

• Append .md to any URL under https://dev.wix.com/docs/ to get its markdown version.
• Pages are either content pages (article/reference text) or menu pages (a list of links to child pages).
• To get a menu page, truncate any URL to a parent path and append .md (e.g. https://dev.wix.com/docs/sdk.md, https://dev.wix.com/docs/sdk/business-solutions.md).
• Top-level index of all portals: https://dev.wix.com/docs/llms.txt
• Full concatenated docs: https://dev.wix.com/docs/llms-full.txt
• §3 points at a local inline recipe per capability — Read it first (first priority); it's already curated, so read it as-is rather than re-discovering the shape. For a pinned SDK doc link (inside a recipe, or the blog supplement in §3), curl its .md directly.
• SearchWixSDKDocumentation is second priority — for discovering a method the recipe doesn't pin, or when a menu hides the runtime functions. Curling a module menu (e.g. …/sdk/business-solutions/blog.md) often surfaces only dashboard/extension pages, not the runtime query functions — SearchWixSDKDocumentation "blog query posts" returns the actual posts.queryPosts/listPosts shapes (with ?apiView=SDK schema links) the menu doesn't expose.

After deploy: finalize per the project type

The guide describes the backend; how the site is published and how its origin is allowed to call Wix depend on the project type. After deployment, finalize per <TYPE_DIR>/DEPLOYMENT.md — it carries the type-specific steps (and tells you whether anything is required of the user).

After emitting the document

Once the guide is emitted and the deployment checklist is done — site published, origin registered (or the user has been flagged) — the skill's work is done. Close with a short plain-prose summary of what was set up (apps installed, content seeded per capability, site published, origin registered or pending). What happens with the guide — installing packages, wiring components, choosing a framework — is the host's to decide.