Index of every page on this site: llms.txt
All skills
wix avatar

/wix-app

@e2bc48e official
by Wix.comwix/skills40 stars
42
Run it yourself

Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, context providers, function libraries, lightbox (popup) behavior, page onLoad contexts, backend APIs, backend events, service plugins, data collections, and App Market readiness. Use when building ANY feature or extension for a Wix CLI app or preparing a Wix app for App Market review. Triggers on: add, build, create, implement, help me, dashboard, widget, plugin, backend, API, event, collection, embedded script, service plugin, Editor React component, context provider, function library, onLoad, on page load, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, lightbox, admin panel, menu item, modal, validate, test, verify, register extension, App Market, app review, submission readiness.

Use this Skill: https://skilld.dev/gh/wix/skills/wix-app

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesPAGE_ON_LOAD.md

≈2.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Page onLoad

Studio 2 editor only. This extension type works only on sites built in the Studio 2 editor. It does not run on Harmony, the classic Wix Editor or Wix Studio (Editor X), so do not offer it for those sites. It is a context provider, and apps can't currently provide contexts: if wix.config.json has "projectType": "App", tell the user before building.

Creates a side-effect-only page context for Wix CLI applications: a context whose only job is to run a piece of logic once, the moment the page is rendered. It exposes no API to other components — it is not meant to be consumed via a hook. The user attaches it to a page in the Editor (Page Settings → Contexts) and the side effect fires on page render.

This is the onReady / page onLoad use case. Typical requests:

  • Send a page_view BI / analytics event with the page name and the visitor's locale
  • Read utm_source, utm_medium, utm_campaign from the URL and send a campaign_attribution event on one named page (capturing across whichever/any page site-wide is an Embedded Script extension instead — see the callout below)
  • Fire an ab_exposure event with the experiment id and the bucketed variant, before the visitor interacts

Mental model: Context → useEffect(..., []) → side effect. The call lives inside useEffect, with an empty dependency array so it fires exactly once on mount.

⚠️ This is a Wix Extension Type — register it

A page onLoad context is a registered Wix context provider extension (extensions.contextProvider()), scaffolded with wix generate. Do NOT ship a loose createContext file in src/site/ or src/contexts/ and wrap the app with it manually — that bypasses the Wix extension system and cannot be bound to a page in the Editor.

Because this context exposes nothing and only performs a side effect, do not add signals service, bindable items, or consumer-facing API machinery.

⚠️ This does not auto-apply to future pages. Binding this context to N pages only covers those N pages today — a page created next month gets nothing until someone binds it manually. Phrasing like "whichever page," "any page," "wherever they land," or "every page" means this case, even without the words "future" or "later" — don't wait for the request to say "future pages" explicitly. If it applies, that's an Embedded Script extension instead of a page onLoad context — build it from EMBEDDED_SCRIPT.md: it activates once and covers the whole site automatically, with no per-page setup, ever.

Quick Start Checklist

  1. First rule out the every-page-automatically case (see callout above) — watch for phrasing like "whichever page," "any page," or "every page load," not just literal mentions of "future" pages. If it applies, stop and build an Embedded Script extension instead (see EMBEDDED_SCRIPT.md). Otherwise, apply the reuse test: glob src/extensions/site/contexts/page-on-load*/ (the trailing * also catches a legacy flat page-on-load/ folder from before task-derived naming) and read the useEffect in each match — does a context for this exact task already exist, and would its current behavior also correctly satisfy this request? If yes → don't create a new one — bind the existing context to any additional page(s) that need it too (no code change). If no (this is a genuinely new task, or the task is conceptually similar but needs different behavior) → create a new, more specifically-named context (see Naming).

  2. Scaffold the context with the Wix CLI, from the project root:

    npx wix generate --params '{"extensionType":"CONTEXT_PROVIDER","name":"Page On Load <Task Name>"}'

    The CLI derives the folder and file names (page-on-load-<task-kebab-case-name>), the type (with the app's own code identifier — no need to ask the user), a fresh id, and the src/extensions.ts registration (see Naming). It creates src/extensions/site/contexts/page-on-load-<task-kebab-case-name>/ with a .tsx and a .extension.ts that hold a counter example.

  3. Run npm install @wix/site if the effect sends analytics events: analytics comes from it, and it is often only a transitive dependency

  4. Rewrite page-on-load-<task-kebab-case-name>.tsx: a createContext + Provider that runs the requested logic inside useEffect(() => { ... }, []), exports the hook, and exports the component as default

  5. In page-on-load-<task-kebab-case-name>.extension.ts, replace the counter's context with { items: {} } and its data with {} (both are required manifest fields), set contextSpecifier.hook to the hook you export, and add contextSpecifier.moduleSpecifier (the scaffold omits it, see Naming)

  6. Tell the user to attach the context to each target page in the Editor via Page Settings → Contexts — repeat per page when reusing one context across pages (manual step)

Naming

Every onLoad context is named after the task it performs — never derived from which page(s) it happens to be bound to. A context can be bound to any number of pages over its lifetime (see the reuse test in step 0), so a page-derived name would go stale, and the target page isn't always identifiable from the request anyway. Derive <TaskName> (PascalCase) from what the effect does — e.g. capturing UTM/click-id params → UtmCapture, logging a page view → PageView, checking an A/B exposure → AbExposure. This mirrors the one-token-derivation approach CONTEXT_PROVIDER.md uses for <ComponentName>, just keyed by task instead of a page or a user-chosen component name.

Thing Name
Component / default export PageOnLoad<TaskName> (e.g. PageOnLoadUtmCapture)
Context PageOnLoad<TaskName>Context
Hook (contextSpecifier.hook) usePageOnLoad<TaskName>
Module specifier (contextSpecifier.moduleSpecifier) <moduleSpecifierPrefix>page-on-load-<task-kebab-case-name>, where <moduleSpecifierPrefix> is @/ by default, or the prefix the user gives you. Never change it once the context exists
Folder and files page-on-load-<task-kebab-case-name> (+ .tsx, .extension.ts) — generated by the CLI from name

Always keep the PageOnLoad prefix — this artifact has no business identity of its own (never consumed as a real API), so the prefix marks it as this pattern at a glance. If a context for the exact same task, with the exact same behavior, already exists somewhere in the app, reuse it (see step 0) instead of duplicating it. If the behavior needs to differ even slightly, that's a different task — give it its own, more specific name rather than reusing.

Hard Constraints

  • The side-effect call MUST live INSIDE the useEffect — never at module scope. Module-scope side effects break SSR and run at import time, not on page render.
  • The dependency array MUST be empty ([]) — this is what makes the effect run exactly once, on mount (page render).
  • The context MUST expose no API — set context: { items: {} } in the registration. This context is not bindable or consumable from other surfaces.
  • Do NOT use signals service here — it is required only when a provider exposes reactive state. A side-effect-only context exposes nothing.
  • A context may be bound to multiple pages when the same task belongs on all of them — reuse it, don't duplicate it (see the reuse test in step 0). Different tasks on the same page are separate contexts, each bound independently — there's no "one context per page" limit.
  • For async work (e.g. an awaited BI call), define an async function inside the effect and call it — do NOT make the useEffect callback itself async.
  • NEVER use mocks, placeholders, or TODOs. Implement complete, production-ready logic.

Reference Documentation

  • PROVIDER.md — the provider component, the extension registration, binding to a page, runtime support and code quality. Read it before writing the .tsx.
  • EXAMPLES.md — documented imports and onLoad templates by use case.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warningstoday4 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    This skill provides a comprehensive environment and set of tools for building Wix CLI app extensions. It includes detailed instructions, API references, and local utility scripts for development tasks like SDK lookup and accessibility auditing. All operations and dependencies are standard for the Wix developer platform.

  • Sockettoday

    1 alert: gptAnomaly

  • Snyktoday

    Risk: MEDIUM · 1 issue

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at e2bc48e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 days ago
compatibility
requires `@wix/cli` >= 1.1.192.

README badge

README badge for wix/skills/wix-app

Builds dashboard pages, modals, plugins, custom widgets, Editor React components, backend APIs, events, service plugins, and data collections for Wix CLI apps. Provides decision logic, API patterns, and validation workflows; scaffolding is owned by the Wix CLI via `wix generate --params`.

Generated from the current SKILL.md.

What extension types does this skill cover?
All Wix CLI app extension types: dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, backend events, service plugins, and data collections.
Does this skill scaffold the extension files for me?
The Wix CLI owns scaffolding via `wix generate --params` for all extension types except Backend API. This skill provides decision logic, API guidance, and business-logic patterns to fill in the generated stubs. Backend API files must be created manually.
What Wix CLI version is required?
The skill requires @wix/cli >= 1.1.192.
Do I need to create a Data Collection extension for app-specific data?
Yes, if you're saving or persisting app-specific data, managing domain entities in a dashboard, or running a service plugin that reads app-configured data. The skill infers this automatically—you don't need to explicitly request it.
Does this skill cover Wix Stores API usage?
Yes. When using any Wix Stores API (products, inventory, orders), the skill requires dual V1/V3 catalog support and references the Stores Versioning guide for module selection and field mapping.

Generated from the current SKILL.md. These answers refresh after source changes.