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

Uninstall create-flex-plugin

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

/usr/local/lib
├── 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

Refer to our Installation Guide for the Flex Plugins CLI.

Migrate your Plugin

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

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

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

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

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

1. Login to the Plugins Dashboard via the Admin UI.

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

Plugins deployed via the Assets UI

Most plugins were originally uploaded to the Twilio Assets UI. 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

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

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.

• Upgrading v1 to v2
• Upgrading v2 to v3
• Upgrading v3 to v4

Next Steps

• Familiarize yourself with common workflows you can implement using the Plugin CLI
• See the full reference guide for the Plugin CLI
• Get back into plugin development with the Plugin Quickstart