Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Migrate Legacy Plugins to the CLI

As of version 4.0.0, the Flex Plugin Builder is installed and managed as a Twilio CLI plugin. The CLI is the primary way of creating, building, deploying and managing your Flex Plugins. This document covers the process of configuring your development environment to work with the Flex Plugins CLI. You will also learn how to migrate your existing plugins to the CLI.

  • The plugins built via the Plugins CLI takes precedence over legacy plugin deployments. If you already have a plugin active within Flex, you can safely deploy that same plugin using the Plugins CLI. We will identify the conflict (identified by the plugin's filename) and only serve the version indicated by the CLI.
  • Flex supports mixed-deployments that include both legacy and Plugins API configurations. You can migrate a single plugin via the Plugins CLI without needing to update all of your plugins together.

Configure your local environment

configure-your-local-environment page anchor


If you already have the beta version of the Plugins CLI installed, install the latest version of the CLI by running the following command

twilio plugins:install @twilio-labs/plugin-flex

Keep in mind that you are no longer required to pass the --beta flag while running the upgrade-plugin command to update your plugins.

Uninstall create-flex-plugin

uninstall-create-flex-plugin page anchor

In the legacy plugin builder, the create-flex-plugin node package is used when you create new plugins. In the Flex Plugins CLI, this package will be managed automatically for you. Use the following command to check whether the create-flex-plugin package is installed as a global package.

$ npm list -g --depth 0
├── create-flex-plugin@3.0.0
├── npm@6.14.7
├── twilio-cli@2.6.0

When installed globally, your existing create-flex-plugin version will be used when creating a new plugin. By uninstalling create-flex-plugin, you ensure that you'll always use the latest version for any new plugin. You can uninstall this package with the following command:

npm uninstall -g create-flex-plugin

Install the Flex Plugins CLI

install-the-flex-plugins-cli page anchor

Refer to our Installation Guide for the Flex Plugins CLI.



The following steps should be executed for each plugin you want to migrate. All commands will be executed within the directory that contains your plugin code.

1. Check whether your Plugin is using an older (<4.0.0) version of the Plugins CLI

1-check-whether-your-plugin-is-using-an-older-400-version-of-the-plugins-cli page anchor

Installing or updating to the latest version of the Plugins CLI does not automatically update your plugins. You must individually update each plugin to the latest version of the Flex Plugins CLI. You can verify the version of your plugin by checking the flex-plugin dependency within your plugin's package.json. Legacy plugins use a version below 4.0.0.

"dependencies": {
"flex-plugin": "^2.0.0",

2. Update your plugin dependencies

2-update-your-plugin-dependencies page anchor

In the directory of your plugin run the following CLI command. This command updates your plugin dependencies to use the latest version of Plugins CLI.

twilio flex:plugins:upgrade-plugin

The command updates the scripts and the dependencies in package.json of your plugin. This command will not override any custom dependencies you've added to package.json.

In the directory of your plugin delete the package-lock.json file and node_modules directory.

Run the following command to reinstall your dependencies

npm install

3. Deploy with Flex Plugins CLI

3-deploy-with-flex-plugins-cli page anchor

Use the CLI's deploy command to allow your plugin to be managed by the CLI and the Plugins Dashboard. Refer to our deployment and release guide for details on this process.

The deploy command will make your plugin available on the Plugins Dashboard. However it will not be live for your agents, and it will not yet replace the legacy plugin you are using. This will happen once you use the CLI's release command, or you release the plugin using the Plugins Dashboard.

4. Remove legacy assets

4-remove-legacy-assets page anchor

You should remove the legacy build of your plugin that you previously deployed to Flex. Only remove this asset once you have confirmed Flex is actively using the plugin version you have deployed using the CLI. You can confirm your active plugins with this command:

twilio flex:plugins:describe:release --active

Removing legacy assets via the Plugins Dashboard

removing-legacy-assets-via-the-plugins-dashboard page anchor
  1. Login to the Plugins Dashboard via the Admin UI(link takes you to an external page) .
  2. The migrated plugins with legacy builds are grouped together and tagged as Duplicate on the Plugins Dashboard. You can delete the legacy builds of the plugin only when your migrated plugin is enabled on your Flex application. This is to ensure that the agents are served with the functionality via the migrated plugin before you delete the legacy build.
  3. Click on the "Delete Legacy Plugin" to start and click on the confirm button to complete the process. The confirmation dialog will show all the builds that will be deleted.

Removing legacy assets manually

removing-legacy-assets-manually page anchor

Plugins deployed via the Assets UI

Most plugins were originally uploaded to the Twilio Assets UI(link takes you to an external page). You must use the interface in the Twilio Console to view and delete these assets.

Plugins deployed using v3 Plugin Builder

Version 3 of the Plugin Builder provided the npm run deploy command. This would deploy plugins using the Assets API. To remove these assets, run the following command:

twilio flex:plugins:upgrade-plugin --remove-legacy-plugin

You will have already run upgrade-plugin once on the plugin already. Running it this second time will have no impact on your plugin.

Managing plugins with collaborators

managing-plugins-with-collaborators page anchor

If you are migrating a plugin that is hosted in a shared repository like GitHub, we recommend committing the changes in your remote repository. This ensures that your plugin updates are shared with the rest of your collaborators.

Your collaborators will need to install the Flex Plugins CLI in their own environments. Once they pull down the updates to your plugin, they will be able to continue using the Plugins CLI for managing versions and releases of your plugins.

Manually migrating a legacy plugin

manually-migrating-a-legacy-plugin page anchor

If you are unable to migrate your plugin using the steps above, follow the manual migration guides below. Each guide covers a single-step change between each major release. A plugin that uses v1.1.1 would need to follow the migration guides for v2, v3 and v4.

Rate this page: