wix-cli-extension-registration

name	wix-cli-extension-registration
description	Register Wix CLI extensions with the app in src/extensions.ts. Use when registering new or existing extensions with the main app builder, adding .use() calls, importing extensions, or updating the extensions chain. Triggers include register extension, extensions.ts, app().use(), import extension, extension not appearing.
compatibility	Requires Wix CLI development environment.

Wix App Registration

After creating any extension file, you must update the main src/extensions.ts file to register the extension with the app.

Why Registration Matters

The Wix CLI discovers extensions through the src/extensions.ts file — it's the single entry point that tells the build system which extensions exist. Without registration:

• Dashboard pages won't appear in the sidebar
• Site widgets won't show in the Wix Editor
• Service plugins won't be called during checkout flows
• Event handlers won't receive webhook deliveries
• Embedded scripts won't be injected into site pages

The most common cause of "my extension isn't working" is a missing .use() call in this file.

Simple Pattern (Recommended for Small Apps)

src/extensions.ts - Import and register extensions directly:

import { app } from "@wix/astro/builders";
import { dataExtension } from "./data/extensions.ts";
import { dashboardpageMyPage } from "./dashboard/pages/my-page/extensions.ts";
import { embeddedscriptMyScript } from "./site/embedded-scripts/my-script/extensions.ts";

export default app()
  .use(dataExtension)
  .use(dashboardpageMyPage)
  .use(embeddedscriptMyScript);

Steps for each new extension:

1. Import the extension from its extensions.ts file
2. Add .use(extensionName) to the app chain
3. Chain multiple extensions together

Advanced Pattern (For Large Apps)

src/index.ts - Re-export all extensions:

export { dashboardpageMyPage } from "./dashboard/pages/my-page/extensions";
export { embeddedscriptMyScript } from "./site/embedded-scripts/my-script/extensions";
export { dataExtension } from "./data/extensions";

src/extensions.ts - Register all extensions programmatically:

import { app } from "@wix/astro/builders";
import * as allExtensions from "./index";

const extensionList = Object.values(allExtensions);

const appBuilder = app();
extensionList.forEach((extension) => {
  appBuilder.use(extension);
});

export default appBuilder;

Extension Types Without Registration

The following extension types do not require extensions.ts files:

• Backend API - Astro server endpoints are auto-discovered

Naming Conventions

Extension export names follow this pattern: {extensiontype}{CamelCaseName}

Examples:

• dashboardpageCartPopupManager
• dashboardpluginBlogPostsBanner
• embeddedscriptCouponPopup
• sitewidgetCountdownWidget
• sitepluginProductBadge
• ecomshippingratesCustomShipping

The type prefix is the extension type in lowercase with no separators.

Troubleshooting

Symptom	Cause	Fix
Extension not appearing at all	Missing .use() call	Add import and .use(extensionName) to src/extensions.ts
"Cannot find module" on build	Wrong import path	Verify the path in your import matches the actual file location (relative to src/)
Extension registered but not working	Export name mismatch	Ensure the exported name in the extension file matches the import in extensions.ts
Multiple extensions, only some work	Incomplete chain	Check that every extension has both an import and a .use() call
TypeScript error on .use()	Wrong export type	Ensure extension file uses the correct builder method (e.g., extensions.dashboardPage() not extensions.embeddedScript())