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.
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.
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
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
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.
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.
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.
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
Run the following command to reinstall your dependencies
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.
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
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.
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.
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.
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.
- 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