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.

referencescontext-providerMANIFEST.md

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

Context Provider Manifest and Binding

The Manifest Is the Binding Contract

A binding-only consumer never sees the provider source. It decides what to wire from displayName and description alone, so those fields carry the whole meaning of the value.

  • displayName names the element and the state the value represents.
  • description states exactly when the value is true, and — for items meant to be bound — which element surface to bind it to.
  • Both are translatable free text — displayName max 100 chars, description max 300.

Extension Registration

The generated <provider-kebab-case-name>.extension.ts holds the manifest; fields are in CONTEXT_PROVIDER_SPEC.md.

Context Items

The context.items map defines what the provider exposes to child components. Each item requires a dataType. See CONTEXT_PROVIDER_SPEC.md for all ContextItem fields and constraints.

⚠️ CRITICAL: context vs data Array Format Difference

The context section and data section use different types for array items. Mixing them up causes the checkpoint error arrayItems is missing arrayItems.item or arrayItems.dataItem with dataType.

Section Type Array item key Example
context ContextArrayItems item arrayItems: { item: { dataType: 'text' } }
data ArrayItems dataItem arrayItems: { dataItem: { dataType: 'text' } }

An array of objects follows the same rule in both sections: the object is the array element, so it goes under item (context) or dataItem (data) with dataType: 'data'. Never put data: { items } directly under arrayItems. Editor React Components accept that form, context providers reject it.

// ✅ data section, array of objects
arrayItems: { dataItem: { dataType: 'data', data: { items: { title: { dataType: 'text' } } } } }
// ❌ fails the checkpoint
arrayItems: { data: { items: { title: { dataType: 'text' } } } }

Context Item Shapes

Entries in context.items — functions, arrays, and enums (full type definitions in CONTEXT_PROVIDER_SPEC.md):

context: {
  items: {
    // function — sync or async, optional params, typed returns
    checkout: {
      dataType: 'function',
      displayName: 'Checkout',
      function: {
        parameters: [
          { dataType: 'text', displayName: 'Payment Method', description: 'How to pay' },
          { dataType: 'number', displayName: 'Tip', optional: true },
        ],
        returns: { dataType: 'data', data: { items: { success: { dataType: 'booleanValue' }, orderId: { dataType: 'text' } } } },
        async: true,
      },
    },
    // array of objects — nest another arrayItems inside `item` for multi-dimensional structures
    products: {
      dataType: 'arrayItems',
      displayName: 'Product List',
      arrayItems: {
        item: { dataType: 'data', data: { items: { name: { dataType: 'text' }, price: { dataType: 'number' } } } },
      },
    },
    // enum: at least 2 options; a single fixed value is `text` (with no `textEnum` key)
    tier: {
      dataType: 'textEnum',
      displayName: 'Subscription Tier',
      textEnum: { options: [{ value: 'basic', displayName: 'Basic' }, { value: 'premium', displayName: 'Premium' }] },
    },
  },
},

Context Implementor

Delegates part of the context to a separate component. Useful for item-level contexts with scoped functions (e.g., setAsCurrentItem). contextImplementor belongs in the context section (on a ContextItem or inside a nested ContextDataItems) — never in data.

context: {
  items: {
    lineItem: {
      dataType: 'data',
      data: {
        items: {
          id: { dataType: 'text', displayName: 'Item ID' },
          name: { dataType: 'text', displayName: 'Name' },
        },
        contextImplementor: {
          componentType: '<codeIdentifier>.lineItemContext',
          propKey: 'lineItemData',
        },
      },
    },
  },
},

The implementor component must be part of the same application and is rendered inside the parent's tree, giving it access to the parent context.

Resources

Field Type Required Description
resources.client.url string Yes Path to the ESM bundle (provider component)
resources.editor.url string No Path to editor-specific bundle (mock/default data)
resources.contextSpecifier.hook string Yes The exported hook name (e.g., useMyContext)
resources.contextSpecifier.moduleSpecifier string Yes <moduleSpecifierPrefix><provider-kebab-case-name> (max 100 characters). Registered Wix-wide, so it must carry the <moduleSpecifierPrefix> prefix; never change it once the provider exists. Does not have to be an NPM package

componentType already exists (code 2018)

Component type '<type>' is already registered by another component (code 2018, componentType already exists). The platform's background preview reports it. The type is built from name (<codeIdentifier>.<camelCaseName>) and is globally unique, so a second extension with the same name is rejected. Give the new extension a different name and type, and a different moduleSpecifier (never rename one that was already released).

Editor Binding

Context is consumed via Editor Binding: a native Editor element receives context data and methods as props, without importing the hook or having a direct dependency on the provider's bundle. The editor UI lets the site owner connect an element's props to a context provided by any component above it in the React tree. From the element's perspective this is identical to receiving static props — it doesn't know or care whether the values come from context or direct configuration.

A native, non-React Wix Editor element already on the stage — a built-in Heading, Text, Button, Image — consumes context by having the site owner connect a context item to one of the element's surfaces:

Element surface Context item type to bind
visibility.hidden / visibility.collapsed / visibility.removed (true = not shown) booleanValue
text content text or number (converted to rich text by the platform)
click / event handler function with parameters: [] (the event is not a parameter)

One item, one surface, straight through — the value reaches the element unchanged apart from the platform's automatic type conversion, with no expression layer in between. This is the constraint that governs what the provider must expose: see Derived Values and The Manifest Is the Binding Contract for how to describe each item so the right binding is chosen.

No consumer is written or registered for this path — the provider is the only code involved, and it is still registered exactly as always, hook export and contextSpecifier included. Plain text and number items connect to Wix's built-in text elements with no additional setup — the platform converts them to rich text at the binding (see Plain Values, Not RichText Twins). A worked end-to-end example is in EXAMPLES.md.

Code Quality Requirements

The project-wide rules are in CODE_QUALITY.md. For a provider:

  • Strict TypeScript with no any types
  • Explicit return types for all functions
  • Proper null/undefined handling with optional chaining
  • Functional components with hooks
  • SSR-safe code (no browser APIs at module scope)
  • No @ts-ignore or @ts-expect-error comments, except the // @ts-ignore directly above an import of a context by its moduleSpecifier (see Importing a Context in Code)
  • Use const/let (no var)

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.