Migrate to a New Site Widget or Plugin Extension

In This Article

If you've built a new site widget or plugin extension to replace an existing one in your app, follow these instructions to transition Wix users smoothly. You can't delete the old extension because doing so breaks the widget for all Wix users who already have the extension installed. Instead, keep both extensions in your app: existing installations continue using the original extension, while new installations automatically receive the updated extension.

Important: Keep the previous extension in your app. If you delete the previous extension, the widget breaks for Wix users who already installed the previous extension on their sites.

Step 1 | Configure the previous extension

Adjust the previous extension's installation settings to prevent sites that install your app later from adding the previous extension, while keeping the previous extension functional for Wix users who already installed the previous extension.

To configure the previous extension:

In the app dashboard, go to Develop > Extensions in the left menu.
Next to the previous site widget or plugin extension you want to replace, click Configure.
Configure the following:

For widgets:
- Where is the widget added when the app is installed?: Select Not added automatically to ensure the widget isn't automatically added to sites that install your app later.
- Show this widget in the Add Elements panel: Turn off this toggle so the previous widget doesn't appear in the Add Elements panel for Wix users.
For plugins:
- Plugin name: Rename the plugin and add "Old" to the name so the previous plugin doesn't appear as a viable option in the plugin explorer for Wix users.
- Add this plugin automatically: Toggle this option off to ensure the plugin isn't automatically added to sites that install your app later.
Click Save.

Step 2 | Notify Wix users who already installed the previous extension about the updated extension

Inform Wix users who already have the previous extension installed that an updated version is available. You can display messages in the following locations:

In the settings panel: Add a notification banner or message at the top of the previous extension's settings panel.
In the extension itself: Display a message inside the widget or plugin that's visible only in the editor, not on the live site.

Your notification should:

Explain that an updated extension with improved features is available.
Tell Wix users where to find the updated extension:
- For widgets: In the Add Elements panel
- For plugins: In the plugin explorer
Provide instructions on how to replace the previous extension with the updated extension.

Notification example

Step 3 | Configure the updated extension

Configure the updated extension to be visible to Wix users and automatically added to sites when Wix users install your app for the first time.

To configure the updated extension:

In the app dashboard, go to Develop > Extensions in the left menu.
Next to the updated site widget or plugin extension, click Configure.
Configure the following:

For widgets:
- Where is the widget added when the app is installed?: Select Added to the site homepage or Added to a site page to automatically add the widget when Wix users install your app for the first time.
- Show this widget in the Add Elements panel: Turn on this toggle so the updated widget appears in the Add Elements panel.
For plugins:
- Plugin name: Ensure the plugin name doesn't include "Previous" so it appears as a viable option in the plugin explorer.
- Add this plugin automatically: Turn on this toggle and select the appropriate slot to automatically add the plugin when Wix users install your app for the first time.
Configure the default preset and any other installation settings as needed.
Click Save.

Step 4 | Release as a minor version

When you're ready to release the app version with these changes, select Minor version as the release type.

To release a minor version:

In the app dashboard, go to the Distribute tab.
Go to either the App Distribution page or the Versions page.
Click Release Version.
Select Minor version as the release type.
Click Release Version & Update.

Wix users who are on the current major version immediately see the updated extension in the Add Elements panel and receive the update automatically.

Note: If Minor version isn't available as an option, you may need to release a Major version. However, major updates require Wix user action to install, so use the major version option only when necessary.

Special considerations

For legacy custom element widgets and iframes

Legacy custom element widgets and iframe components don't show in the Add Elements panel by default. To mark these as not added to the site, contact Wix support for assistance.