The Wix Gotchas Nobody Documents — What I Learned Building With Claude

Every platform has its paper cuts. Most platforms document theirs, eventually. Wix CLI — the framework for building apps that install into Wix sites — has a set of sharp edges that I've found exclusively by cutting myself on them.

These are not conceptual mistakes. They're the kind of thing that wastes two hours and leaves no trace in the official docs: the config field that silently breaks the build, the dev server that hangs in the background, the release command that confidently ships stale code. A senior developer hitting them for the first time would lose the same two hours I did.

I'm writing them down here so they don't have to.

1.`wix release` does not rebuild. Ever.

This one broke a production release.

I had finished a round of fixes, committed, pushed, and ran npx wix release. The release succeeded. I sent the installer link. The user installed it, found nothing had changed, and reported back that the bugs were still there.

What happened: wix release uploads whatever is currently in the dist/ folder. It does not rebuild. It does not check whether the code in dist/ matches the code in the repo. It just zips and ships. The dist/ folder was from the previous build session, the previous day.

The fix is a two-step sequence that should live in muscle memory:

rm -rf dist && npx wix build
ls -la dist/   # verify today's timestamp
npx wix release -t minor -c "..."

If dist/ shows yesterday's date, you are about to release yesterday's app.

The rule: never run wix release without running rm -rf dist && npx wix build immediately before it. The timestamp check is not paranoia — it is the verification.

2.`wix dev` is interactive-only, and it will hang silently if you forget

npx wix dev uses Ink, a terminal UI library. It requires an interactive TTY. If you try to run it in the background, pipe its output, or automate it through any shell that doesn't have a real terminal attached, it fails silently or hangs.

This matters because it's tempting to have Claude manage the dev server as part of an automated workflow. It cannot. Every time I've tried, the process either errors with "Raw mode is not supported" or sits there consuming nothing and producing nothing.

The correct pattern: Pete runs wix dev in his own terminal. Full stop. The checklist before every dev session:

Kill zombies first: pkill -f "wix dev"
Run from the project root (the .wix/ directory must be present)
Wait for "App Manifest updated" in the output before touching the dashboard
Refresh the Wix dashboard tab after the manifest uploads

The "App Manifest updated" line is the signal the app is live in dev mode. Before it appears, the dashboard shows nothing.

The rule: wix dev is interactive-only. Never automate it. Kill stale processes before starting it.

3.Use Wix Studio as your dev site, not classic Editor

This took forty minutes to diagnose on a fresh app.

I had a new Wix CLI app running, wix dev connected to a site, and every data operation was returning WDE0110: Wix Code not enabled. Nothing in the code was wrong. The app was correctly configured. The issue was the site type.

Classic Wix Editor sites don't have Wix Dev Mode (Velo) enabled by default. @wix/data calls and auth.elevate() both fail with WDE0110 on classic sites. The solution is not to enable Dev Mode on the classic site — the solution is to use a Wix Studio site, which has it enabled from the start.

If wix dev asks you to pick a dev site and you pick a classic Editor site, everything compiles, connects, and then silently fails at runtime.

The rule: always select a Wix Studio site as your dev site. Classic Editor sites cause WDE0110 errors on data and auth. Don't debug the code when the problem is the site type.

4.Two fields in `wix.config.json` will silently break the build

The Wix CLI scaffold generates a wix.config.json with five fields. Two of them — namespace and codeIdentifier — should not exist at all in most apps. If they're present with empty strings, the app fails with a 500 error: "App namespace is not set."

The config that works has exactly three fields:

{
  "appId": "<real-uuid-from-dev-center>",
  "projectId": "my-app-name",
  "projectType": "App"
}

Removing the empty namespace and codeIdentifier entries fixes the error immediately. The scaffold adds them; they should be stripped on every new project.

The same failure mode exists with component IDs. Extension IDs like "ff-home-page" cause "componentId is not a valid GUID" errors. All extension IDs must be UUID format: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c01". Use a GUID generator, not a readable string.

The rule: strip namespace and codeIdentifier from every new wix.config.json. Use UUID format for all extension IDs.

5.Security headers can white-screen your app in ways that look like code bugs

I spent a session debugging a white screen in a prototype. The page loaded, the console showed no JS errors, the network showed requests going out — and the screen was blank. It looked like a rendering bug. It was a header conflict.

Two "textbook correct" security headers had been added without checking the deployment topology:

upgrade-insecure-requests in the CSP: the app sits behind a reverse proxy that terminates TLS. The app server receives HTTP internally. The directive instructed the browser to upgrade sub-resource URLs to HTTPS, the internal server refused, assets failed to load.
X-Frame-Options: DENY: the app is embedded in an iframe by the platform. DENY blocked the host platform from embedding it. White screen.

Neither failure showed up as a clean error. They looked like render failures.

The questions to answer before applying any security headers:

Where does TLS terminate? If at a proxy and not at the app, omit upgrade-insecure-requests.
Is the app embedded in an iframe? If yes, never use X-Frame-Options: DENY. Use CSP frame-ancestors 'self' instead — it's more granular and won't block the host editor.
After every header change, load the page in a browser and check the console. A passing build is not a loading page.

The rule: security headers are deployment-dependent, not universal. Audit the topology before applying them, and verify visually after.

6.Tailwind opacity modifiers silently fail on shadcn/ui colour tokens

This one is specific enough to feel like a footnote — until it's your modal overlay rendering transparent when it should be opaque.

Tailwind's opacity modifier syntax (bg-background/98) assumes the CSS custom property contains raw channel values. shadcn/ui stores bare HSL: --background: 0 0% 4%. Tailwind generates rgb(var(--background) / 0.98), which is invalid CSS — the variable holds HSL, not RGB. The browser silently ignores it.

The symptom: an overlay or dropdown that appears transparent, or a modal background that renders as nothing. The fix is to use explicit hex:

bg-[#0a0a0a]   instead of   bg-background/98

I hit this on an event companion app's navigation overlay. The hamburger menu opened, the content appeared, and the background behind it was completely transparent. Switching to a hardcoded hex colour fixed it in one line.

The rule: never use Tailwind opacity modifiers on shadcn/ui colour tokens. Use explicit hex for any element that needs opacity control.

The pattern underneath

Six different failure modes, and none of them come from bad code. They come from gaps between what the tool documents and what the tool does — the dist/ folder that doesn't rebuild, the TTY that won't run headless, the dev site that silently disables data operations, the config fields that break the build with an empty string.

The discipline that helps: don't diagnose backwards from symptoms. When something breaks in Wix development, check this list before opening the code. Most of the time, the code is fine.

Next in the series · Post 6 of 12

Making AI-Built UI That Doesn't Look AI-Built

1.wix release does not rebuild. Ever.

2.wix dev is interactive-only, and it will hang silently if you forget