Migrate from a Previous Blocks Widget or Plugin Extension to an Updated Extension

You have a Blocks widget or plugin, but Blocks isn't supported in the Wix Harmony editor. To support the new editor, you add a second extension to the same app—built with another framework (for example, the Wix CLI or self-hosting). This task walks you through that migration: configure the existing Blocks extension so new installs get the new extension instead, add and publish the new extension, and keep the Blocks extension for existing users on Wix Editor and Wix Studio.

Important: Keep the previous extension in your app. Deleting it breaks the widget or plugin for Wix users who already installed it on their sites.

Step 1 | Configure the previous extension

Adjust the previous extension's installation settings so that new installs don't add it, while keeping it working for Wix users who already have it installed.

To configure the previous extension:

  1. Open your app in the Blocks editor. To open installation settings:

    • For widgets: Select the previous widget in the App Interface, then click the WixBlocks menu > Dashboard. In the app dashboard, click Installation Settings > Manage Settings. Alternatively, hover over the widget name in the App Interface, click the 3 dots, then Editor Experience > Edit Installation Settings.
    • For plugins: In the Widgets and Design panel, hover over the previous plugin's name, click the Show More icon, then Plugin Settings. The app dashboard opens in a new tab.

  2. Make sure you have the previous widget or plugin selected. For widgets, switch via Extensions in the app dashboard if needed.

  3. Configure the following:

    For widgets:

    • Configure how your widget is added: Select Not added automatically so the widget isn't automatically added to sites that install your app later.
    • Shown in Add Panel: In the Preset Images in Add Panel section, turn off this option for each design preset so the previous widget doesn't appear in the Add + panel for Wix users.

    For plugins:

    • Plugin name: Rename the plugin and add "Old" or "Previous" 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 to the site: Turn off this option so the plugin isn't automatically added to sites that install your app later.

  4. Save your changes. Then build your app again in the Blocks editor so the dashboard changes take effect.

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

Tell Wix users who already have the previous (Blocks) extension installed that a replacement extension built for the new editor is available. You can show the message in either of these places:

  • Settings panel: Add a notification banner or message at the top of the previous extension's settings panel.
  • In the extension: Show 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 (built for the new editor) with improved features is available.
  • Tell Wix users where to find the updated extension in the editor they're using (for example, the Add Elements panel for widgets or the plugin explorer for plugins).
  • Provide instructions on how to replace the previous extension with the updated extension.

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:

  1. In the app dashboard, go to Develop > Extensions in the left menu.

  2. Next to the updated site widget or plugin extension (the one built with your other framework), click Configure.

  3. 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 option so the updated widget appears in the Add Elements panel for Wix users.

    For plugins:

    • Plugin name: Use a clear name so the plugin appears as a viable option in the plugin explorer.
    • Add this plugin automatically: Turn on this option and select the appropriate slot so the plugin is automatically added when Wix users install your app for the first time.

  4. Configure the default preset and any other installation settings as needed.

  5. Click Save.

Step 4 | Release so both extension configurations take effect

You need to release in two places so the previous extension is hidden for new installs and the updated extension is available. When available, release as a minor version so that Wix users on the current major version immediately see the updated extension in the Add + panel for widgets or in the plugin explorer for plugins, and receive the update automatically.

  1. Release in the Blocks editor (so the previous extension's settings from Step 1 take effect):

  2. In the Blocks editor, click Release.

  3. Select Minor version as the release type, if available.

  4. Confirm to complete the release.

  5. If your app also includes extensions built with a non-Blocks framework (such as the Wix CLI or self-hosting), release your app separately so those extensions go live. Release using whichever method matches the framework:

    If all of your app's extensions are built with Blocks, the Blocks release in the previous step is sufficient.

Note: If Minor version isn't available or appropriate for your changes, 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.

See also

Did this help?