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 components don’t deploy at all, and each wiring section below opens with the files to read before writing their equivalents. Files you edit: SiteLayout.astro and styles/global.css. Files you create: your home page, any gated page the brief asks for, and your own account surface if the reference one doesn’t fit the brand.

Astro stack additionally gets:

What you build — this is the design job, not optional polish

You implement the surfaces yourself, styled with Tailwind utilities on the @theme tokens, designed to fit the brief (a members-only club and a course platform should not get the same account area):

1. The login page — the chrome around the shipped LoginForm (pages/login.astro): heading, what membership gives, the brand. The form’s four states already render; you own the page.
2. The account page — pages/account.astro mounts RequireAuth around AccountView; keep the gate, and replace AccountView with your own surface on useMember when the brief wants more than the profile card (orders, bookings, saved items — each from its own vertical’s data layer).
3. The header control — the shipped MemberMenu or your own on useMember: it is the one surface every page shows, so it carries the brand.
4. Gated content the brief asks for — a page inside RequireAuth, or a member-only section on a public page rendered from loggedIn.
5. The home page — on SiteLayout, with the way in (log in / join) visible.

Plus the theme (edit the @theme block in styles/global.css — one edit) and the chrome (header/footer in SiteLayout.astro, one edit pass).

What a complete members site shows (recommended defaults)

Defaults for a brief that says nothing about them; the prompt wins when it asks for something else. Then, by default:

• Header: a skeleton while the session read settles, “Log in” for a visitor, the member’s name or avatar plus “Log out” for a member — never a flash of “Log in” for someone who is in.
• Login page: sign in and sign up on one page; email verification and owner approval rendered as states (a code field, a “pending approval” notice), a failed login as an inline message next to the form; ?returnTo= honoured after success (the shipped form does all of this).
• Account page: gated — a visitor sees the login prompt in place, a member their real profile (displayName, loginEmail, memberSince, photo when there is one); a logged-in member with member === null gets the one honest line (“profile details unavailable”) — the Members Area app isn’t installed, which the seed does.
• Logout: returns to the page that offered it, or the home page.
• Copy: nothing the owner didn’t supply — no invented perks, member counts, or testimonials; no Wix IDs or technical words in visible text.

The contracts your components consume (everything you need — don’t read the source)

The pages — the shipped shells and a gated page

Hooks first, branches after (an early return above a hook changes hook order between renders and React throws). Session-reading islands mount client:only="react" — they read browser state and must not server-render; a client:load gate would flash the logged-out state. One island per gated surface: nest RequireAuth around the view inside a React component and mount that component from the .astro page. Children written in the .astro file (<RequireAuth client:only="react"><AccountView /></RequireAuth>) are rendered once on the server as static HTML and never hydrate — the view stays on its loading placeholder forever.

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

On lib, static, and a port, nothing under components/ or hooks/ arrives. The state machine behind the hook does arrive — wix/members/member-store.ts — so you never rewrite it: subscribe, render from getMemberState(), call its actions; MemberState is the render contract. What you write is the rendering — the form, the gate, the header control — and for that read these first; they are tested code for exactly that behaviour, and rewriting them from the prose above is where the bugs come from:

1. components/members/LoginForm.tsx — the four states as working code: the sign-in/sign-up toggle, the name fields only on sign-up, the verification-code step, the pending notice, the inline error, the button disabled while busy, returnTo after success (only a same-site path).
2. components/members/RequireAuth.tsx — wait for loading to settle before deciding (deciding early bounces a member on first paint); the visitor’s prompt links to the login page with the current path as returnTo.
3. components/members/MemberMenu.tsx — the three renders (skeleton, “Log in”, name/avatar + “Log out”) and the avatar fallback (first letter of displayName).

All under templates/members/app/.

Wiring — Astro (default)

1. Set the @theme tokens (one edit); brand SiteLayout.astro (one pass), keeping one <MemberMenu client:only="react" /> in the header.
2. Keep /login and /account as shipped — the only login surface is /login, and the shipped form already posts to the integration’s built-in routes. Never build a callback page, a login API route, or a redirect to a Wix login page: @wix/astro (2.75 or later) ships them (/api/auth/login, /signup, /verify-email, /reset-password, /logout, /callback), on by default. Brand the chrome around the mounts; replace AccountView with your own surface on useMember when the brief wants more.
   • Social login when the brief asks: a plain link <a href="/api/auth/login?idp=google&returnToUrl=/account"> (also facebook) — the provider must be enabled in the dashboard’s login settings.
   • Forgot password when the brief asks: a plain <form method="post" action="/api/auth/reset-password"> with email and failureUrl; Wix hosts the reset itself and the member signs in again after.
3. Gated content: RequireAuth around it, client:only="react".
4. Write pages/index.astro (home) on SiteLayout.

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

Read the reference files listed above before writing any surface.

deploy.mjs members --stack lib put the data layer in src/wix/ and nothing else: sdk.ts, config.ts (deploy wrote the public client id into WIX_CLIENT_ID), media.ts, and wix/members/ — client.ts, auth.ts, members.ts, types.ts, the *-core.ts rules, and member-store.ts. None of it is React. The hook and the components don’t ship on this stack; the store replaces the hook, and you write the components in your framework to the contracts on this page:

• bind the store with your framework’s external-store primitive (Vue: shallowRef updated in subscribeMember; Svelte: readable(getMemberState(), (set) => subscribeMember(() => set(getMemberState()))); Solid: a signal set in subscribeMember). One store for the whole app (module-level); the first subscriber triggers the session read. State in, actions out — exactly useMember‘s contract;
• your login form, gate, and header control to the defaults above — LoginForm.tsx, RequireAuth.tsx, MemberMenu.tsx are readable as behaviour specs.

Routes /login, /account (gated in the component, not the router — the session is browser state); 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.

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 layer from the site’s js/wix/ folder and write every control on the stores; static.md shows how to drive each store, with the header control, the login page, the gate, the routes, the rules and the seed.

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

Read the reference files listed above before writing any surface.

Run deploy.mjs members --stack static in the project folder anyway: js/wix/ is both the browser-side code and the readable spec. This vertical has no public reads — everything is the visitor’s own state — so the whole flow runs in the browser from ./js/wix/ exactly as the static wiring above: the login form, the gate, the header control on member-store.js; the browser owns the member token, so the server handles no per-visitor tokens, and a member-only page is a page whose content renders once getMemberState().loggedIn is true. Add your public https origin to the OAuth app’s allowed domains before the login can complete (the iframe exchange) and before logout can return.

If the server itself must know the member (server-rendered member-only pages, member-owned data joined server-side), port js/wix/auth.ts and auth-core.ts: the same three calls — login with a visitor token, the redirect session, POST /oauth2/token with grantType: "authorization_code" — and the no-DOM branch of the exchange (fetch the authorize page, read code and state from it) is the server’s path; or use the docs’ full-page variant (responseMode: "query" plus a redirectUri on the allowed list). Then client.ts‘s header applies: one token set per visitor in the visitor’s session, never one process-wide token, and GET /members/v1/members/my?fieldsets=FULL with that token on each request (members.ts + members-core.ts as the port).

Wiring — React SPA (Vite etc.)

Import ./styles/global.css once at the app entry (needs @tailwindcss/vite in the vite config plugins — deploy already added the dep). Write route wrappers in the project’s router: /login → a page mounting LoginForm (pass onSuccess to navigate with your router, or let it use ?returnTo=); /account → RequireAuth around your account surface; gated routes → the same. Mount MemberMenu in the header (pass LinkComponent for router links). Deploy wrote the public client id into wix/config.ts (WIX_CLIENT_ID); nothing else to configure. Here the login runs in the browser on the shared client, and a SUCCESS is a session at once (no round trip).

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

• No Wix-hosted login page, and no auth code of your own. The member types credentials into your form on your site. On managed Astro the shipped transport posts them to the built-in /api/auth routes and the round trip through /api/auth/callback is the integration’s, never a page you write; elsewhere the shipped SDK exchange runs. Password reset and logout return to a URL you pass.
• Auth only through the shipped exports — useMember / the store's actions; never call the IAM API or the OAuth client yourself, never rewrite the exchange. Extend by adding a function in wix/members/ for what they don’t cover (API contracts: the wix-docs skill).
• One auth seam (wix/sdk.ts, reused by wix/members/client.ts) — never instantiate another client, never one per component, never read or write the session cookie yourself.
• Session state only through the store — no React context, no copy of loggedIn in component state, no identity inferred from local UI state.
• Every state is rendered: a failed login shows error next to the form; verification and owner approval are states, not errors; loading is a skeleton, never the logged-out UI.
• Identity vs profile: loggedIn needs no app install; member (profile data) needs the Wix Members Area app — the seed installs it. A member with member === null gets the honest line, not a fake profile.
• Gate only what the brief gates. Public pages stay public; browsing never needs a login.
• Don’t use auth.elevate() for a member reading their own records — the member token is the right identity.
• Live data or an honest empty state — never mock a member, a name, or a member count.
• The session persists on its own (an HttpOnly cookie the integration writes on Astro, the shared client’s localStorage tokens elsewhere); never mint per page, never store credentials.
• Where the shipped components deploy (Astro, React): theme via the @theme tokens, and your markup uses Tailwind utilities on the same tokens — one design system across shipped and written code. Where they don’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.
• Call every hook before any conditional return. Hooks first, branches after.

Point the user to their dashboard

Give the owner the dashboard link — the deploy step’s JSON output already printed it (dashboardUrl); copy, don’t re-derive. Members are managed under Contacts → Site Members there, and the signup policy — email verification, owner approval, reCAPTCHA — is set under Settings → Member signup; it decides which state a sign-up ends in.

Seeding

Per seed/SEED.md — seed-members.mjs, run from the project root. It installs the Wix Members Area app (the profile layer) and nothing else: members self-register at runtime, never at build time. Independent of the frontend work.