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

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

Loading Pattern: The Complete Provider

Read the page's own context first. This example fetches a Bookings service with the SDK only to show the loading pattern. When the data belongs to Stores, Blog, Bookings or Events and the site already provides that context (VERTICAL_CONTEXTS.md), read the hook instead: no SDK call and no serviceId field. A provider that only reads a vertical hook still exposes the loading pair, derived from the loading and error fields that context lists (for example isLoading and hasError). Use this pattern for data no context provides.

The Pattern

One provider, complete. Everything after this section explains a decision visible in it — read the code first, then the rules.

From the request "On my service page, show the name and price of the service from Wix Bookings, and show a grey placeholder bar in place of each while it loads. The Contact Us button and the header image should stay visible the whole time. Use context providers and native components, do not create an editor react component."

@wix/bookings appears only because this is a Bookings example — the pattern does not depend on it. Substitute whatever data source the request names. The one package the pattern itself requires is @wix/react-use-promise-polyfill, for use().

src/extensions/site/contexts/booking-service-context/booking-service-context.tsx:

import React, {
  Suspense,
  createContext,
  useContext,
  useRef,
  useState,
} from 'react';
import { use } from '@wix/react-use-promise-polyfill';
import { services } from '@wix/bookings';
import type { BooleanValue, Text } from '@wix/editor-react-types';

// Use the SDK's own exported entity type. Do NOT derive one from the method —
// see "Name the entity type, do not derive it" below.
type ServiceDetails = services.Service;

export interface BookingServiceContextType {
  serviceName: Text;
  servicePrice: Text;
  isPlaceholderHidden: BooleanValue;
  isContentHidden: BooleanValue;
  showService: (serviceId: string) => void;
}

export interface BookingServiceProviderProps {
  children?: React.ReactNode;
  serviceId: Text;
}

interface BookingServiceInternalProps {
  children?: React.ReactNode;
  initialServicePromise: Promise<ServiceDetails | null>;
}

const BookingServiceContext = createContext<BookingServiceContextType | null>(null);
BookingServiceContext.displayName = 'BookingServiceContext';

export function useBookingServiceContext(): BookingServiceContextType {
  const context = useContext(BookingServiceContext);
  if (!context) {
    throw new Error(
      'useBookingServiceContext must be used within a BookingServiceContextProvider',
    );
  }
  return context;
}

// The only place the SDK is called, and it never rejects — see "The fetch
// wrapper must never reject" for why, and why the id guard is there.
const fetchService = (serviceId: string): Promise<ServiceDetails | null> => {
  if (!serviceId) {
    return Promise.resolve(null);
  }
  return services.getService(serviceId).catch((): null => null);
};

// Every key the manifest declares, at placeholder values — a missing key breaks its binding.
const placeholderApi = (): BookingServiceContextType => ({
  serviceName: '',
  servicePrice: '',
  isPlaceholderHidden: false,
  isContentHidden: true,
  showService: () => {},
});

// Keeps children rendered while the initial promise is pending. No spinner here —
// the treatment lives in the bound elements.
function BookingServiceContextFallback({
  children,
}: { children?: React.ReactNode }): React.ReactNode {
  return (
    <BookingServiceContext.Provider value={placeholderApi()}>
      {children}
    </BookingServiceContext.Provider>
  );
}

BookingServiceContextFallback.displayName = 'BookingServiceContextFallback';

// Outer — owns the boundary AND the initial promise. It never calls use(), so it
// never suspends and its state survives. The default export the runtime loads.
export function BookingServiceContextProvider({
  children,
  serviceId,
}: BookingServiceProviderProps): React.ReactNode {
  const [initialServicePromise] = useState(() => fetchService(serviceId));

  return (
    <Suspense
      fallback={<BookingServiceContextFallback>{children}</BookingServiceContextFallback>}
    >
      <BookingServiceContextInternal initialServicePromise={initialServicePromise}>
        {children}
      </BookingServiceContextInternal>
    </Suspense>
  );
}

// Internal — suspends on the initial promise under the boundary above. It
// consumes the promise and never creates one.
function BookingServiceContextInternal({
  children,
  initialServicePromise,
}: BookingServiceInternalProps): React.ReactNode {
  const initialService = use(initialServicePromise);

  const [service, setService] = useState<ServiceDetails | null>(initialService);
  const [isFetching, setIsFetching] = useState(false);
  // A ref, not state — this guard must never trigger a re-render.
  const latestRequest = useRef(0);

  const showService = (nextServiceId: string): void => {
    const requestId = latestRequest.current + 1;
    latestRequest.current = requestId;
    setIsFetching(true);
    fetchService(nextServiceId).then((nextService) => {
      // A slower earlier request must not overwrite a newer one.
      if (latestRequest.current !== requestId) {
        return;
      }
      // A failed fetch settles to null. Writing that would discard the service
      // already on screen, so only a real result replaces it.
      if (nextService !== null) {
        setService(nextService);
      }
      setIsFetching(false);
    });
  };

  // Derived at render time from the state — never stored in a second state value.
  const serviceName = service?.name ?? '';
  const servicePrice = service?.payment?.fixed?.price?.formattedValue ?? '';

  const api: BookingServiceContextType = {
    serviceName,
    servicePrice,
    isPlaceholderHidden: !isFetching,
    // Independent of isPlaceholderHidden, not its complement — during a refetch both are false.
    isContentHidden: service === null,
    showService,
  };

  return (
    <BookingServiceContext.Provider value={api}>{children}</BookingServiceContext.Provider>
  );
}

BookingServiceContextInternal.displayName = 'BookingServiceContextInternal';
BookingServiceContextProvider.displayName = 'BookingServiceContextProvider';
export default BookingServiceContextProvider;

context, data and contextSpecifier in src/extensions/site/contexts/booking-service-context/booking-service-context.extension.ts (the rest of the file is generated by wix generate):

context: {
  items: {
    serviceName: {
      dataType: 'text',
      displayName: 'Service name',
      description: 'Name of the service currently being shown. Bind to the service name text element content.',
    },
    servicePrice: {
      dataType: 'text',
      displayName: 'Service price',
      description: 'The service price, already formatted in the site currency. Bind to the price text element content.',
    },
    isContentHidden: {
      dataType: 'booleanValue',
      displayName: 'Content is hidden',
      description: 'True when no service is loaded. Bind to the hidden property of the name and price elements.',
    },
    isPlaceholderHidden: {
      dataType: 'booleanValue',
      displayName: 'Loading placeholders are hidden',
      description: 'True when no fetch is in progress. Bind to the hidden property of the grey placeholder bars.',
    },
    showService: {
      dataType: 'function',
      displayName: 'Show a different service',
      description: 'Loads another service and swaps it in without blanking the page. Bind to a service link or button click handler.',
      function: {
        parameters: [
          {
            dataType: 'text',
            displayName: 'Service ID',
            description: 'ID of the service to show.',
          },
        ],
        async: false,
      },
    },
  },
},
data: {
  serviceId: {
    dataType: 'text',
    deprecated: false,
    displayName: 'Service ID',
  },
},
resources: {
  contextSpecifier: {
    hook: 'useBookingServiceContext',
    moduleSpecifier: '<moduleSpecifierPrefix>booking-service-context',
  },
},

What the Site Owner Binds

Each text element's content goes to serviceName or servicePrice (the platform converts text to rich text at the binding), and both elements' hidden property to isContentHidden. The grey placeholder bars bind their hidden property to isPlaceholderHidden. The Contact Us button and header image are bound to nothing — no visibility binding, so they stay visible throughout.

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.