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
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
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
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
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.
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
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.