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-loadPROVIDER.md

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

Page onLoad Provider and Registration

Provider Component Pattern

Goes in page-on-load-<task-kebab-case-name>.tsx. UtmCapture below is the example task, not a fixed name — replace that token everywhere it appears (component, context, hook, folder, both filenames) with the task-derived name for the actual request (see Naming).

import React, { createContext, useContext, useEffect } from 'react';

// No API is exposed — the context value is always `undefined`.
const PageOnLoadUtmCaptureContext = createContext<undefined>(undefined);
PageOnLoadUtmCaptureContext.displayName = 'PageOnLoadUtmCaptureContext';

// A hook is exported because the manifest's contextSpecifier.hook is required.
// It is intentionally not meant to be consumed by other components.
export function usePageOnLoadUtmCapture(): undefined {
  return useContext(PageOnLoadUtmCaptureContext);
}

export interface PageOnLoadUtmCaptureProps {
  children?: React.ReactNode;
}

export function PageOnLoadUtmCapture({
  children,
}: PageOnLoadUtmCaptureProps): React.ReactNode {
  useEffect(() => {
    // The requested side effect goes here. For async work, define and call an
    // inner async function — do not make the effect callback itself async.
    const run = async (): Promise<void> => {
      // e.g. send a BI / analytics event, read UTM params from the URL...
    };
    void run();
  }, []); // empty deps → runs once, on page render

  return (
    <PageOnLoadUtmCaptureContext.Provider value={undefined}>
      {children}
    </PageOnLoadUtmCaptureContext.Provider>
  );
}

PageOnLoadUtmCapture.displayName = 'PageOnLoadUtmCapture';
export default PageOnLoadUtmCapture;

The hook (usePageOnLoad<TaskName>) and the default export are required by the Wix extension manifest (contextSpecifier.hook) and runtime loader, even though nothing consumes the hook. The context and the component can't share a name, so they are PageOnLoad<TaskName>Context and PageOnLoad<TaskName>.

Key rules for the provider component

  • Always set displayName on both the context and the provider component.
  • Always accept children and render them inside the Provider — the page's content renders as children of the context.
  • Always export the provider as both a named export and default — the Wix runtime loads the provider via its default export.
  • The context value is always undefined — this provider exposes no API.

Extension Registration

wix generate writes page-on-load-<task-kebab-case-name>.extension.ts and registers it in src/extensions.ts. Edit the generated file; the finished shape of the parts you change, for the example task UtmCapture (substitute your task per Naming):

// No exposed items and no inputs: both fields stay, empty (they are required).
context: { items: {} },
data: {},
resources: {
  client: {
    url: './extensions/site/contexts/page-on-load-utm-capture/page-on-load-utm-capture.tsx',
  },
  contextSpecifier: {
    // Required by the manifest even though nothing consumes it.
    hook: 'usePageOnLoadUtmCapture',
    moduleSpecifier: '<moduleSpecifierPrefix>page-on-load-utm-capture',
  },
},
  • hook must be the exact hook name the provider file exports. The scaffold's useCounterContext stops existing when you rewrite the file.
  • moduleSpecifier is <moduleSpecifierPrefix> plus the folder name. Module specifiers are unique across all of Wix, so an unprefixed one can belong to another app and fail the checkpoint with Error during component specifier upsert.
  • Dependencies. Run npm install @wix/site: it provides analytics, and is often present only as a transitive dependency.
  • Unique type. The type is built from the context's name and is globally unique. A second context with the same name fails with componentType already exists (code 2018), which the platform's background preview reports: rename it.
  • data is only needed if the side effect must be configurable from the Editor (e.g. a configurable event name); otherwise keep data: {}.

Binding to a page (manual)

After creating and registering the context, tell the user to attach it to each target page in the Wix Editor:

Open <page name> → Page Settings → Contexts → add the context you registered, listed under its name (for example Page On Load Utm Capture).

Reusing one context across pages means repeating this step per page, not creating a new context per page. Binding is a manual Editor step today — do NOT attempt to bind the context to a page programmatically.

Examples

See EXAMPLES.md for documented imports and page onLoad templates by use case. Examples share the provider shape shown above; substitute the task-derived name (see Naming) — only imports and the body of the useEffect change per use case.

⚠️ Runtime support — use @wix/site analytics + browser-native APIs; NEVER use @wix/site-*. @wix/site (analytics.trackEvent) works, but the separate @wix/site-* packages (@wix/site-window, @wix/site-location, @wix/site-seo) throw Wix Site SDK only works in a Wix site environment in the Studio 2 runtime — even when the provider is correctly bound and the effect is firing. Read URL/UTM params from window.location.search and the visitor locale from navigator.language (both inside the useEffect); do not import @wix/site-window or @wix/site-location. Setting SEO tags is out of scope for page onLoad — there is no client-side path and a client effect can't reach crawlers; set SEO server-side (router response.data / the page's SEO settings) instead. See EXAMPLES.md.

Code Quality Requirements

  • Strict TypeScript, no any.
  • Explicit return types for all functions.
  • SSR-safe: no browser APIs at module scope. Browser globals (window, navigator) are fine inside useEffect (client-only); guard defensively with if (typeof window !== 'undefined').
  • Functional components with hooks; const/let only.
  • No @ts-ignore. The one exception in CODE_QUALITY.md is for importing another context, which this context never does.
  • Always set displayName on the context and the provider.

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.