INSTRUCTIONS

The file map (deployed into src/)

On Astro and React the shipped files are tested and work as they are — this table and the contracts below are everything you need to use them, so don’t spend the run reading their source; wire them and build your surfaces. Reading them is the right move when something is off (a runtime error, a field this playbook doesn’t cover) or when the brief wants a behaviour they don’t offer — then read the file that owns it and change or extend it. On lib, static, and a port the hooks don’t deploy at all; the stores behind them do, and each wiring section below says how to bind them. Files you edit: SiteLayout.astro and styles/global.css. Files you create (skeletons below): the listing and item pages with their islands, plus your home page.

There are no shipped components — the data layer, stores, and hooks are the machinery; every component is yours.

Astro stack additionally gets:

There are no shipped pages — you author them (below).

What you build — the design job

Read the seed plan first: its collections, field keys, and permissions are the contract your pages bind to (collection ids and field keys verbatim).

1. A listing surface per content collection — your card (image, title, secondary fields) and rhythm, with skeletons while loading and an honest empty state — on useCollection (or SSR via queryItems alone when the page needs no interactivity).
2. An item page per collection with a slug field — your detail layout on the DTO (SSR fetch via getItemBy), with a real 404 on miss.
3. The home page — hero, featured items (fetch in frontmatter → your components), brand story.

Plus the theme (@theme block, one edit) and the chrome (SiteLayout, one pass). Style everything with Tailwind utilities on the tokens.

What a complete content site shows (recommended defaults)

Defaults for a brief that says nothing about them; the prompt wins where it differs. Look at the seeded content before designing (how many collections, which fields, whether items carry images and dates) and design for this content, not for a stereotype of the business.

• Home: what the site is about and one path into the content in the first screen; real items under truthful headings; not a repeat of a listing page.
• Listing: a real card — image, title, a secondary field — in the first screen; each item a link to its item page (/<collection>/<slug>); loading, empty, and error states that look different; “load more” when hasNext (or a numbered pager when the brief asks for pages). A filter or sort change keeps the cards on screen and dims them (fetching) — skeletons only before the first answer.
• Item page: title, image, the date formatted, the body as HTML, related items only when a reference field carries them; a slug that resolves to nothing shows only the not-found state.
• Copy: nothing the owner didn’t supply — no invented fields, counts, or authors; no Wix IDs or technical words in visible text.

The contracts your components consume

Everything you need — tested and working as they are; read a file when something is off or the brief wants more.

The pages and islands you create — skeletons

The class names in these skeletons are the Astro/React spelling of layout rules that hold on every stack, and each rule is also named in words beside its classes. On a stack where the hooks don’t deploy (lib, static, a port), keep the rule and write it in your own CSS.

Each page is a thin SSR shell (fetch → DTO props → island, or no island when the page has no interactivity); each island is a thin view over a hook. Hooks first, branches after. The islands render on the server too (client:load SSRs), and by then the 200 and headers are already sent — a render throw truncates the body mid-stream. Render every state totally; nothing in a render path may throw.

The reference files for stacks where the components don’t deploy

On lib, static, and a port, nothing under hooks/ arrives, and CMS ships no components. The state machines behind the hooks do arrive — wix/cms/collection-store.ts, item-store.ts — so you never rewrite them: create a store per surface, subscribe, render from getState(), call its actions. Their CollectionState / ItemState interfaces are the render contract; read those. What you write is the rendering — cards, the item view, the states — to the skeletons above. The two hooks under templates/cms/app/hooks/cms/ are the binding pattern, ten lines each, if your framework’s external-store primitive is unfamiliar.

Wiring — Astro (default)

1. Set the @theme tokens (one edit); brand SiteLayout.astro (one pass) and add one nav link per content surface.
2. Author your pages under src/pages/ per the skeletons above — SSR fetch in the frontmatter, DTO props to your islands (client:load; a page with no interactivity needs no island at all).
3. Write pages/index.astro (home) on SiteLayout.
4. Author your surfaces in as few messages as possible — batch multiple Writes per message (components and pages are independent files).

Wiring — another JS framework (--stack lib: Vue, Svelte, Solid, plain Vite)

deploy.mjs cms --stack lib put the data layer in src/wix/ and nothing else: sdk.ts (the visitor client, configured with the public client id), media.ts, money.ts, and wix/cms/ — items.ts, types.ts, items-core.ts, and the two stores collection-store.ts, item-store.ts. None of it is React. The hooks don’t ship on this stack; the stores replace them, and you write the components in your framework to the contracts on this page:

• bind the stores with your framework’s external-store primitive (Vue: shallowRef updated in subscribe; Svelte: readable(store.getState(), (set) => store.subscribe(() => set(store.getState()))); Solid: a signal set in subscribe). createCollectionStore({ collectionId, filters?, sort?, limit?, include?, withTotal?, initialItems? }) per listing (start() when mounted, stop() when unmounted, setQuery() when filters change, loadMore() or goToPage(n), refresh() after a write), createItemStore({ collectionId, ref: { id } | { by }, initialItem? }) per item surface. State in, actions out — exactly the hooks’ contracts above.

Routes /<collection>, /<collection>/:slug (via getItemBy, null → your 404); dev server on 4321; a static build goes through npx @wix/cli@latest release with site.outputDirectory pointing at the build folder, an SSR build is hosted by you. Page tags from the item’s own fields.

Wiring — static site (--stack static, no bundler)

Read static.md in this folder: it is the whole playbook for this stack, in one file. The pages import the modules from the site’s js/wix/ folder and write the rendering on the stores; static.md shows how to drive each store, with the listing, the item page, the routes, the rules and the seed.

Wiring — server-rendered, another language (Flask, Laravel, Rails, …)

Run deploy.mjs cms --stack static in the project folder anyway: js/wix/ is both the browser-side code and the readable spec. Then split by where the call runs. Reads on the server: port js/wix/items.ts and items-core.ts to your language — queryItems, getItemBy, getItemById, countItems returning the same DTO shapes as dicts (the core’s toValue rules: { "$date": iso } → ISO string, wix:image:// → the https URL form in media.ts, 1200 wide at the aspect the id’s #originWidth/#originHeight fragment gives), one anonymous visitor token per process for these public reads (mint and refresh per client.ts) — and render the listing and item pages in your templates to the contracts above, so titles are in the HTML; page tags from the item’s fields. Visitor writes in the browser (a collection the seed opened to visitors or members): insertItem from ./js/wix/items.js on the page, exactly as the static wiring above — the browser owns the visitor token, so the server handles no per-visitor tokens. Routes stay /<collection>, /<collection>/<slug>.

Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted. Same port for the reads, run at build time with one anonymous token; the generator must emit every item page (walk queryItems by skip until hasNext is false — never only the first page). Run deploy.mjs cms --stack static --out <build dir> so js/wix/ is inside the output the pages import from, point site.outputDirectory at that folder, wix release. Pages sit at different depths (/, /<collection>/…): give the templates one base path to js/wix/ (a template variable, or root-relative /js/wix/…), never a relative ./js/wix/ — it breaks one level down. The frozen listing is the first paint; a filter or “load more” still runs client-side on it through createCollectionStore() from ./js/wix/collection-store.js, exactly as on a static site. Close with the live URL, the rebuild + release command, and one line for the owner: dashboard edits to the content reach the site when that command runs.

Wiring — React SPA (Vite etc.)

Import ./styles/global.css once at the app entry (needs @tailwindcss/vite in the vite plugins — deploy added the dep). Routes are yours: a list route per collection on useCollection, a detail route on useItem with by: { field: "slug", value } (components fetch client-side when no initialItems / initialItem is passed). Deploy wrote the public client id into wix/config.ts; nothing else to configure.

Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).

Hard rules

• Data only through the shipped exports — never re-derive a Wix Data request, never import @wix/data directly in your components, never hand-build a static.wixstatic.com URL.
• The id is _id, fields are flat — item.id is undefined; item.data.title is the REST shape and reads undefined.
• Bind by the seed plan’s ids and keys verbatim — collection ids have no namespace; a mistyped field key reads as a blank, not an error.
• An empty read on a PUBLIC collection is a seed permissions bug (read must be ANYONE) — fix the seed, never reach for auth.elevate (it doesn’t exist on this path). On a member-scoped collection an empty anonymous read is the gate working, not a bug.
• updateItem REPLACES the whole item — omitted fields are wiped. Spread the full item, or use patchItemFields. Date fields on any write are Date objects — a round-tripped ISO string is silently stored as text and breaks date queries.
• Writes 403 unless the collection was seeded with that verb open — surface a 403 as a permissions setup step (which permission, where in the dashboard), not a code bug. Anything that needs elevated access runs server-side per templates/shared/CUSTOM_OPERATIONS.md.
• User-created content is a CMS contribution flow. For a member or visitor submission that the app must later list, use the seeded CMS collection and its intended permission preset. If the operation needs elevated access — especially a browser-created file that must enter Media Manager — follow templates/shared/CUSTOM_OPERATIONS.md: validate the caller and input in a narrow server endpoint before elevating one documented operation. Never call a privileged Media API directly from a client island.
• Use the shipped upload capability when it fits. Declare its named policy in plan.capabilities.mediaUpload; Fast deploys the endpoint, client helper, dependencies, and generated policy module. Your CMS surface calls uploadMedia(policyId, file) and stores the returned Wix Media reference. Do not author another upload endpoint for that flow.
• RICH_TEXT is HTML, not plain text — render it with set:html (Astro) / dangerouslySetInnerHTML (React) on a wrapper; never interpolate it as text.
• Dates through formatDate, images through imgAttrs — the DTO’s ISO string and https URL are data, not copy. The URL is at the photo’s own aspect; imgAttrs defaults to a square srcset, so pass imgRatio(url) ?? 1 (natural) or a fixed ratio (uniform cards) — never leave a 4:3 photo to be cropped square by default.
• Reference fields hold ids unless the query passed include — don’t render an id as content. getItemById‘s include rides the get request’s includeReferences key (the installed typings’ spelling); confirm once on a live site that it comes back with full items — if it returns ids, use getItemBy(collectionId, "_id", id, { include }), the query path Wix’s own components use for that reason.
• A MULTI_REFERENCE is never written through data — insert and update drop the value silently (200, no error). Create the item, then linkItems (or insertItem(…, { link })); unlinkItems removes. A single REFERENCE is set at insert as the target item’s _id.
• After a write, refresh() the listing — the store can’t know, and Wix Data is eventually consistent (a read right after a write may not show it yet); refresh() re-reads what is on screen without skeletons. Never splice the written item into the list by hand.
• Guard absent IMAGE fields — imgAttrs returns {}; render a fallback, never an empty/broken <img>.
• Page at the source, not on a loaded list. hasNext/loadMore() append the next page from Wix, goToPage(n) replaces it; never raise the page limit instead of paging, never filter or sort client-side a page you already hold — pass filters/sort and let Wix apply them across the collection; filter chips come from distinctValues, not from the page in hand. between is [start, end) — a date range’s end is the first excluded day.
• CMS as a product catalog is the storefront’s job — selling CMS items through a checkout needs the ecom path the storefront vertical owns; deploy storefront for that, don’t rebuild it on a collection.
• Call every hook before any conditional return. An island that returns early for notFound/loading above its hooks changes hook order between renders and React throws.
• Where the shipped code deploys with Tailwind (Astro, React): theme via the @theme tokens, your markup on the same tokens; no parallel theme files, no hardcoded palettes. Where it doesn’t (lib, static, a port): style with whatever your stack does well, on one token set of your own; the rule that survives is the token set, not Tailwind.
• Live data or an honest empty state — never mock items or invent fields not in the plan.

Point the user to their dashboard

Hand the owner these links — {siteId} is siteId in wix.config.json (the deploy JSON prints it as dashboardUrl); a collection id is its _id (the seed result lists them).

Seeding

Per seed/SEED.md — plain-data plan.json into seed-cms.mjs from the project root. The plan is the content model your pages bind to: design collections that exercise the UI (a slug field per detail page, an IMAGE field with a verified imageUrl per item, a DATE field when the content is chronological).