From wix-headless
Use when scaffolding, configuring, building, previewing, or deploying a Wix Managed Headless project. Triggers: headless project setup, scaffold, wix dev, wix build, wix preview, wix release, wix connect, deploy, configure, environment variables, ship it, see my changes live.
npx claudepluginhub wix-playground/skills-architecture-test --plugin wix-headlessThis skill uses the workspace's default tool permissions.
Manages the lifecycle of Wix Managed Headless projects: scaffolding, linking, credentials, development server, build, preview, and release.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
Manages the lifecycle of Wix Managed Headless projects: scaffolding, linking, credentials, development server, build, preview, and release.
Before doing anything, check for a headless project:
Check for: wix.config.json AND astro.config.mjs (or .ts)
| State Detected | Action |
|---|---|
| Neither file exists | Scaffold a new project → see Scaffold a New Project |
astro.config.mjs exists but no wix.config.json | Link to Wix → see Link Existing Project |
Both exist but no .env.local | Guide user to pull credentials → npx @wix/cli env pull |
Both exist + .env.local present | Project is ready — proceed with the user's request |
| WRONG | CORRECT |
|---|---|
npx @wix/cli dev in a non-headless project | Check for wix.config.json + @wix/astro first |
Running astro dev instead of npx @wix/cli dev | Always use npx @wix/cli dev — it injects Wix credentials |
Manually editing .env.local WIX_CLIENT_* vars | Use npx @wix/cli env pull — these are auto-managed |
Manually editing wix.config.json | This file is auto-generated — never edit manually |
Running npx @wix/cli release without previewing | Always run npx @wix/cli preview and verify before releasing |
Committing .env.local to git | Add to .gitignore — contains sensitive credentials |
The agent can scaffold a new project using --json non-interactive mode.
Prerequisite — verify authentication:
npx @wix/cli whoami
If this fails, tell the user to run npx @wix/cli login first (the only manual step).
Run the scaffold command:
npx @wix/create-headless --json \
--business-name "<name>" \
--project-name "<directory-name>" \
--site-template-id "<template-uuid>" \
--skip-vibe-setup \
--no-publish \
--skip-install
Required flags:
--json — enables non-interactive mode--business-name <name> — name for the Wix business--project-name <name> — directory name for the local project. Validation: 3–20 characters, lowercase letters and numbers only (no hyphens, underscores, or spaces). Directory must not already exist. Invalid names produce ProjectNameArgumentIsInvalid.--site-template-id <uuid> OR --apps <apps> — one of these is required (see below)Template vs Apps:
--site-template-id <uuid> — use a template for scaffolding (see table below)--apps <apps> — comma-separated Wix apps to install (e.g., --apps stores,forms). Uses a blank template for code scaffolding and installs specified Wix apps on the business. Valid app names: stores, forms, blog.When --apps is used without --site-template-id, the blank vibe template is used for code scaffolding automatically.
Optional flags:
--skip-vibe-setup — skip Wix Vibe coding setup--no-publish — don't publish site after creation--skip-install — skip npm install--skip-git — skip git initKnown issue: non-ASCII business names with --apps:
When --business-name contains non-ASCII characters (Hebrew, Arabic, CJK, etc.) AND --apps is also specified, the scaffold may fail with FailedCreatingAppProject. If this happens, retry with an ASCII-transliterated --business-name (e.g., "Yeshnaeretz" instead of "ישנה ארץ") while keeping --apps. The business display name can be updated later in the Wix dashboard.
Template IDs — Vibe-Compatible:
| Template | Description | ID |
|---|---|---|
| Blank (hello) | Minimal starter with a single hello-world page | a59b41a5-a5db-4d7c-804f-5dbc86e04c3e |
| Stores | E-commerce storefront with product catalog and cart | 38fee0f9-830e-445c-8eec-464455c889b1 |
| CMS | Content-managed site with dynamic data collections | a164bf71-a82e-43b4-a5c9-a037e4345df1 |
Template IDs — Pure Headless:
| Template | Description | ID |
|---|---|---|
| Commerce (Wix Stores) | E-commerce storefront with product catalog and cart | e5da13f4-c01e-4b61-a9c7-55dacd961d54 |
| Registration (Wix Forms) | Form-based data collection and registration | e5d63bf1-cd06-48eb-ad77-0da9235adcf1 |
| Blank | Empty project with Wix SDK wired up, no UI | 212b41cb-0da6-4401-9c72-7c579e6477a2 |
Output: JSON result to stdout: { "projectFolder": "...", "businessId": "...", "projectId": "..." }. Progress and status messages go to stderr.
Errors: { "error": { "code": "...", "message": "..." } } to stdout. Detailed error messages also appear on stderr.
Error recovery — do NOT silently work around failures:
If the scaffold command fails:
--apps flag and install apps separately via MCP. MCP app installation does not fully initialize apps (e.g., Stores V3 catalog won't activate, making product management impossible).--business-name (most common fix for FailedCreatingAppProject)--site-template-id for the app-specific template (e.g., 38fee0f9-830e-445c-8eec-464455c889b1 for stores) instead of --appsThe key principle: when you leave the documented path, ask the user before proceeding — silent workarounds cascade into harder-to-debug problems.
Agent workflow note: Always capture both stdout and stderr. Never redirect stderr to /dev/null — it contains error details needed for debugging failures. Parse JSON from stdout; use stderr for logging and diagnostics.
After scaffolding, cd into the project directory.
Lifecycle logging: After scaffolding succeeds, create .wix/lifecycle.log.md per ../shared/LIFECYCLE_LOG.md. Write the # Lifecycle Log header, the ## Run header (timestamp, site name, business type, planned features), the ### solution-architect phase (from the functional plan context — business type, brand, apps, collections, pages), and the ### cli phase (command, result, project path, business ID, timestamps).
When coming from the solution-architect flow: The functional plan provides --apps and --project-name values. The brand name from the solution architect (if captured) provides --business-name. If the brand name wasn't captured during the solution-architect phase, the designer skill will ask for it during brand discovery.
Do not run npm install yet — dependencies will be installed in a single batch after all code is written. Proceed to the designer skill (wix-headless-designer) for brand discovery and visual design, then to the features skill (wix-headless-features-orchestrator) for SDK integration. See the Build Order section in wix-headless-features-orchestrator for when and how to run the single install.
For an existing Astro project that needs Wix connection. The agent can run this using --json non-interactive mode.
Prerequisite — verify authentication:
npx @wix/cli whoami
If this fails, tell the user to run npx @wix/cli login first.
Run the link command:
npx @wix/create-headless link --json \
--business-name "<name>" \
--project-name "<frontend-name>"
Required flags:
--json — enables non-interactive mode--business-name <name> — name for the Wix business--project-name <name> — name for the frontend projectOutput: Same JSON format as scaffold — { "projectFolder": "...", "businessId": "...", "projectId": "..." } to stdout.
All commands run from the project root.
| Command | Description | Interactive? |
|---|---|---|
npx @wix/create-headless | Scaffold a new project (interactive mode) | Yes |
npx @wix/create-headless --json ... | Scaffold a new project (non-interactive) | No |
npx @wix/create-headless link | Link existing project (interactive mode) | Yes |
npx @wix/create-headless link --json ... | Link existing project (non-interactive) | No |
npx @wix/cli dev | Start local development server with hot reload | No |
npx @wix/cli build | Compile project for production | No |
npx @wix/cli preview | Deploy to temporary preview URL on Wix infra | No |
npx @wix/cli release | Deploy to production (CDN, SSL, auto-scaling) | No |
npx @wix/cli connect | Link project to Wix Vibe for AI editing | Yes |
npx @wix/cli env pull | Pull environment variables to .env.local | Yes (may need auth) |
npx @wix/cli env set <KEY> <VALUE> | Set an environment variable | No |
npx @wix/cli env remove <KEY> | Remove an environment variable | No |
npx @wix/cli generate | Add extensions (dashboard pages, event handlers) | No |
npx @wix/cli login | Authenticate with Wix | Yes |
npx @wix/cli logout | Remove stored credentials | No |
npx @wix/cli whoami | Show current authenticated user | No |
See references/COMMANDS.md for full command details with flags and examples.
1. npx @wix/cli dev → Local dev server (http://localhost:4321)
2. npm install → Ensure dependencies are current
3. npx tsc --noEmit → TypeScript check
4. npx @wix/cli build → Production build
5. npx @wix/cli preview → Deploy to preview URL for testing
6. [Verify preview]
7. npx @wix/cli release → Deploy to production
Key points:
npx @wix/cli dev (not astro dev) — it injects Wix SDK credentialsnpx @wix/cli preview creates a unique URL per deployment; previous previews remain validnpx @wix/cli release deploys to production — verify preview firstproject-root/
├── wix.config.json # Wix app + site IDs (auto-generated, DO NOT EDIT)
├── astro.config.mjs # Astro config with @wix/astro integration
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript config
├── .env.local # Local env vars (auto-populated, DO NOT COMMIT)
├── .wix/ # Wix internal data (DO NOT EDIT)
├── .astro/ # Astro build cache (auto-generated)
├── dist/ # Production build output (auto-generated)
├── public/ # Static assets (favicon, images, robots.txt)
├── src/
│ ├── pages/ # File-based routing (*.astro → routes)
│ ├── components/ # Reusable UI components
│ ├── layouts/ # Page layouts
│ ├── styles/ # Global styles (Tailwind CSS)
│ ├── utils/ # Shared utilities
│ ├── extensions/ # Wix extensions (if any)
│ ├── env.d.ts # TypeScript env types
│ └── extensions.ts # Wix extension registration
└── node_modules/
Auto-generated. Contains appId and projectId. Never edit manually.
{
"appId": "your-app-id",
"projectId": "your-project-id"
}
Required Wix headless configuration:
import { defineConfig } from "astro/config";
import wix from "@wix/astro";
import cloudProviderFetchAdapter from "@wix/cloud-provider-fetch-adapter";
const isBuild = process.env.NODE_ENV === "production";
export default defineConfig({
integrations: [wix()],
...(isBuild && { adapter: cloudProviderFetchAdapter({}) }),
image: {
domains: ["static.wixstatic.com"],
},
output: "server",
});
Standard TypeScript config with React JSX support for React islands.
Auto-populated by npx @wix/cli dev. Contains:
WIX_CLOUD_PROVIDER — Cloud provider (Cloudflare)WIX_CLIENT_ID — App IDWIX_CLIENT_INSTANCE_ID — Instance IDWIX_CLIENT_PUBLIC_KEY — RSA public keyWIX_CLIENT_SECRET — App secretNever commit .env.local to git. Never manually edit WIX_CLIENT_* variables.
For custom env vars, add them to .env.local for local dev and use npx @wix/cli env set for production.
Access in Astro frontmatter:
---
const myKey = import.meta.env.MY_API_KEY;
---
| Command | Purpose |
|---|---|
npx @wix/cli env pull | Pull remote env vars to local .env.local |
npx @wix/cli env set MY_KEY my-value | Set a custom env var (synced to remote) |
npx @wix/cli env remove MY_KEY | Remove a custom env var |
Production: Environment variables are injected automatically by Wix infrastructure during npx @wix/cli preview and npx @wix/cli release. Custom vars set via npx @wix/cli env set are available in production.
npx @wix/cli preview
references/GOING_LIVE.mdAfter running
npx @wix/cli preview: Extract the site URL from the command output and present it prominently to the user. This is their headless site URL — they need it to view their site. If the URL is not visible in the output, tell the user to check the Wix dashboard under Settings > Domains.
npx @wix/cli release
references/GOING_LIVE.mdAfter running
npx @wix/cli release: Extract the production site URL from the command output and present it prominently to the user. This is their live headless site URL. If the URL is not visible in the output, tell the user to check the Wix dashboard under Settings > Domains.
Configured in the Wix business dashboard (manual step):
After any code change (bug fix, feature addition, component edit), run this validated sequence to build, preview, and surface the URL.
npx tsc --noEmit
Catches type errors faster than a full build. Fix any errors before proceeding.
npx @wix/cli build
Success: Exit code 0, produces dist/ directory.
On failure: Common fixes:
npm install -D @wix/cloud-provider-fetch-adaptertsc → Fix and re-run from Step 1Prerequisite: Step 2 MUST have completed successfully. Preview uploads the build output — without it, you get "Project build output is missing".
npx @wix/cli preview
After npx @wix/cli preview succeeds:
.wix.dev or similar)npx @wix/cli release when ready to go liveOn failure: Check .wix/debug.log for details. If build succeeded but preview fails, run npx @wix/cli env pull and retry.
| User Wants | Redirect To |
|---|---|
| "Build me a website", describe their business needs | wix-headless-solution-architect |
| Design my site / brand / style / visual | wix-headless-designer |
| Add a feature (form, products, blog) | wix-headless-features-orchestrator |
| Build a Wix app (not headless) | This is NOT a headless project |