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.

There are two ways to use the Flex Plugin Builder. You can add it to the Twilio CLI with a CLI Plugin. Alternatively, you can use the Flex Plugin Builder as a standalone tool. The Plugin Builder 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.

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

When we update the Plugin Builder and its dependencies, we do not push these changes automatically to your existing plugin repositories. To check the latest versions of the packages the Plugin Builder uses:

  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.0  →  ^3.0.1
    
    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.

Plugins deployed using npm run deploy rely on the Functions & Assets API, which is currently available as a beta release and 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. For example:

#!/bin/bash
# This script runs within your plugin directory
npm install
npm run test
npm run lint
TWILIO_ACCOUNT_SID=ACXXXX TWILIO_AUTH_TOKEN=pass123 npm run deploy

Make sure to handle your AccountSid and Auth Token as environment variables or arguments passed into your scripts.

Deploying your plugin

The primary new interface is an npm run deploy command. This command will build your plugin and deploy it 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.

Deleting your Deployed Plugin

If you want to delete a plugin you already deployed, in your terminal run:

npm run remove

The command requires a confirmation on whether you want to delete your plugin:

Screen Shot 2019-10-07 at 10.57.02 AM.png

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

Upgrading Plugin Versions

When you create a new plugin, the version of the Plugin Builder you are using is based on the create-flex-plugin node package that is installed on your machine. You can use the following command to check which version you have installed:

$ npm list -g --depth 0

/Users/jdoe/n/lib
├── create-flex-plugin@3.0.0
├── npm@6.9.0
└── yarn@1.10.1

If create-flex-plugin is installed globally, that version will be used when generating your new plugin directory. If it is not installed globally, then the latest version will be used when executing the initializer

npm init flex-plugin plugin-sample --install

Prior to npm@6, the initializer would not use a globally installed package. So if you directly called npx create-flex-plugin, it would also use the latest published version of the Plugin Builder.

However, existing plugin directories are not automatically updated to use the latest features from the Plugin Builder. These must be individually migrated to add the new build scripts and apply updated dependencies. You can verify the version of your plugin by checking the flex-plugin dependency within your plugin's package.json.

"dependencies": {
    "flex-plugin": "^1.1.1",
    ...,
}

Migrating Existing Plugins from v1 to v3

If you are migrating a plugin from v1, you must first make updates to support v2. These changes are documented within Github as part of our CHANGELOG. 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",
    "prebuild": "rm -rf build && npm run bootstrap",
    "build": "flex-plugin build",
    "clear": "flex-plugin clear",
    "predeploy": "npm run build",
    "deploy": "flex-plugin deploy",
    "eject": "flex-plugin eject",
    "postinstall": "npm run bootstrap",
    "list": "flex-plugin list",
    "remove": "flex-plugin remove",
    "prestart": "npm run bootstrap",
    "start": "flex-plugin start",
    "test": "flex-plugin test --env=jsdom"
  }
}

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

{
  "craco-config-flex-plugin": "^3.0.0",
  "flex-plugin": "^3.0.0",
  "flex-plugin-scripts": "^3.0.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@2.9.2

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.