Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Flex Plugin Builder

Flex Plugins are the recommended way of customizing the Flex UI. Plugins have access to all of the frontend APIs: adding and replacing components, using the Actions Framework, triggering Notifications, and more. And they provide a few additional benefits:

  • Plugins can be applied to any running Flex instance. This lets you use the same plugins across projects that simulate dev/stage/prod environments, and it's also the preferred path for any partner integration.
  • It decouples the customizations from individual flex-ui versions. As new versions are released, the plugins do not need to be rebuilt and redeployed.
  • It allows for modular development. Plugins can be scoped to particular pages, personas, or functions to help separate concerns.

The Plugin Builder is our interface for developing, testing, and releasing a plugin. It is an open source project, available on npm and Github, that creates a React environment using Facebook's create-react-app. You will typically use the following technologies when building a Flex Plugin:

  • JavaScript or TypeScript, as your primary language for building a frontend experience
  • React, to interface with Flex's UI components or to create your own
  • Node, to run the development environment and start your local webserver

Using the Plugin Builder

The Plugin Builder is initiated from your command line. A new project will generate a directory that houses everything you need to interact with Flex's frontend APIs and run a local instance of the UI. By default, creating a project and then running npm start will start a local webserver, launch Flex, and display a component that demonstrates changing the default experience. The Plugin Quickstart walks through a full end-to-end example.

There's a few items to keep in mind when developing with the Plugin Builder:

  • Each project is intended to create a single plugin. If you want to build multiple plugins, you would initiate the Plugin Builder for each one.
  • Your plugin will build against the version of flex-ui which is referenced in your package.json. For example, if this is "@twilio/flex-ui": "^1", then you would start with the latest release of Flex UI v1. However, if new flex-ui versions are released, you'll only pull those in after an npm update.
  • All of your custom development will happen within the /src folder of your plugin. Only that code will be bundled when building a release of your plugin.
  • The /public folder holds the assets which will be served by your local webserver. This is where you could update your appConfig.js if there are any Flex Configuration values to update, or you could update plugins.json to load additional plugins alongside your development.
  • /public/index.html should not be updated for development. If you intend to load additional external resources, like JS or CSS assets, you can use the loadJS and loadCSS functions exposed in the flex-plugin library.
  • Although running locally, the Flex UI is still interacting with Twilio's live APIs. Be aware that tasks you complete and messages you send could potentially impact your production account. This is why we recommend developing on a dedicated 'dev' Twilio Project.

BETA


This Twilio product is currently available as a beta release. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA.

See this article for more information on beta product support.

The Plugin Builder v3 leverages the Functions & Assets API to automate the release process of plugins. This allows you to deploy your plugins via command line, without needing to manually upload them from the Twilio Console.

This automation also supports integrating your Flex Plugin development into a CI/CD pipeline.

Installation

This beta release is not latest on npm, and it must be installed explicitly. However the beta release is tagged with next in npm. In your terminal, run the following command:

npm install -g create-flex-plugin@next

Deploying your plugin

The primary new interface is an npm run deploy command. This command will build your plugin and deploy to Twilio Assets from your CLI. You no longer need to drag-and-drop your plugin within the Twilio Console.

When you are ready to deploy your plugin, in your terminal run:

npm run deploy

This will publish your plugin as a Private Asset that is accessible by the Functions & Assets API. If you want to deploy your plugin as a Public Asset, you may pass --public to your deploy command:

npm run deploy --public

For more information on Public vs Private plugins, please see Deploying Flex Plugins.

Using Multiple AccountSids

To use the Functions & Assets API, the Plugin Builder needs to use your Twilio auth credentials. These will be stored locally in your keychain (or Windows Credential Vault) so you do not have to re-enter your credentials every time.

If you are deploying your plugins to multiple accounts, you will need to provide credentials for each account. New pairs of AccountSid and AuthToken credentials may be provided as environment variables with the deploy command:

TWILIO_ACCOUNT_SID=ACxxx TWILIO_AUTH_TOKEN=abc123 npm run deploy

This will use the newly provided credentials and save them in the keychain. If you have multiple accounts saved and you do not provide credentials along with your deploy command, then you will be prompted to select one:

? Select from one of the following Account Sids (Use arrow keys)
 AC0000000000000000000000000000000 
  AC0000000000000000000000000000001
  AC0000000000000000000000000000002

Keeping up-to-date with the latest versions of Plugin Builder

While Plugin Builder v3 is in Beta and not latest on npm, you will need to update your dependencies manually to receive the latest updates.

To find out the latest versions of the packages used:

  1. Install the npm-check-updates package globally: npm install -g npm-check-updates
  2. In your plugin root directory run the ncu command, and you will see an output like:
    ncu -n
    Checking ~/plugin-vs/package.json
    [====================] 21/21 100%
    
     craco-config-flex-plugin  ^3.0.12-alpha.0  →   ^3.1.3-alpha.0
    
    Run ncu -u to upgrade package.json​
    
  3. In this example, there is an update available for craco-config-flex-plugin package. Bump this in your package.json and run npm install again.

Migrating Existing Plugins from v1 to v3

If you are migrating from Plugin Builder v1, review the CHANGELOG on how to migrate from v1 to v2 before migrating to v3. v3 builds on the changes and improvements done in v2.

Migrating Existing Plugins from v2 to v3

Functions & Assets API uses a different version of Assets than the existing version of Twilio Console Assets. As part of the migration, after you've uploaded all your existing plugins using Plugin Builder v3, you'll need to delete the original files from Twilio Console Assets.

Edit the package.json of your existing plugin and replace the scripts section with:

{
  "scripts": {
    "bootstrap": "flex-plugin check-start",
    "postinstall": "npm run bootstrap",
    "prestart": "npm run bootstrap",
    "start": "flex-plugin start",
    "build": "flex-plugin build",
    "predeploy": "npm run build",
    "deploy": "flex-plugin deploy",
    "test": "flex-plugin test --env=jsdom",
    "list": "flex-plugin list",
    "clear": "flex-plugin clear",
    "remove": "flex-plugin remove",
    "eject": "flex-plugin eject"
  }
}

Then edit the dependencies section and add/update the following 3 dependencies:

{
  "craco-config-flex-plugin": "^3.6.2-beta.0",
  "flex-plugin": "^3.6.2-beta.0",
  "flex-plugin-scripts": "^3.6.2-beta.0",
}

Re-run npm install, and you'll now have the latest version.

Once you have uploaded all your new plugins, head over to Twilio Console Assets and remove them from the UI so Flex does not serve duplicate plugins.

Reverting back to Plugin Builder v2

If you upgraded to the Plugin Builder v3 but want to revert back to v2, there are three steps to follow:

Migrate Plugins

For each plugin that has been deployed using the Plugin Builder v3:

Downgrade Each Plugin

Edit the package.json of your existing plugin and replace the scripts section with:

{
  "scripts": {
    "bootstrap": "flex-check-start",
    "build": "craco build",
    "eject": "craco eject",
    "postinstall": "npm run bootstrap",
    "prestart": "npm run bootstrap",
    "start": "craco start",
    "test": "craco test --env=jsdom",
    "coverage": "craco test --env=jsdom --coverage --watchAll=false"
  }
}

Then edit the dependencies section to remove flex-plugin-scripts and update the following entries:

{
  "craco-config-flex-plugin": "^2",
  "flex-plugin": "^2",
}

Then re-run npm install to install the appropriate dependencies.

Downgrade create-flex-plugin

Install the original version of create-react-plugin using:

npm install -g create-flex-plugin
Rate this page:

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 browsing the Twilio tag on Stack Overflow.