@twilio/flex-ui-dev-proxy

flex-ui-dev-proxy

One ore more of the services that we use in Flex might not allow requests from localhost due to their CORS configuration.

The first service to do that is GoodData, which we use for displaying historical reporting. GoodData themselves recommend setting up a local proxy for development, but they only support Webpack.

We realize that not everyone uses Webpack and to make developer experience as good as possible, we came up with this package that you can run locally while developing plugins for Flex, without having to deal with any CORS issues.

When do I need this?

If you are a developer working on a plugin for Flex, and you need access to historical reporting dashboards, or if you're seeing connectivity issues to localhost:8081 in your Flex and you don't know what that means.

The problem

During the initialization phase, Flex will try to authenticate against GoodData application running on our custom domain analytics.ytica.com. Because the origin of that request is either localhost or some arbitrary domain, due to the configuration of the service the browser will reject the response.

The rejected response contains necessary set-cookie headers, containing the auth token, which means that the authentication will fail.

We can work around this by using a proxy running on localhost, rewriting the origin of the request and cookie domain, along with removing Secure flag and SameSite=None from set-cookie headers, allowing us to run this on http and not force everyone to switch to https.

Flex knows to target http://localhost:8081 when running in development environment. This can bechanged.

Usage

RECOMMENDED - Running a standalone application

To run the proxy as standalone app locally on http://localhost:8081, which is the default configuration, run npx @twilio/flex-ui-dev-proxy. You can specify the port with a -p parameter and host with -h.

To list all of the options, use --help.

Running proxy on https

In some use cases, it may be required for the proxy to be running on https. To do that, please pass a --https parameter.

When you run the proxy on https for the first time, you will be asked to generate a self-signed certificate. Having a certificate on your server is a requirement for the https to work.

The app uses openssl library to generate the certificate, please make sure it is installed and present in path.

Using the middleware

You can also import the createDevProxyMiddleware from @twilio/flex-ui-dev-proxy package in your custom express server and use it in your existing stack. The function takes an optional serviceUrl: string argument and returns the middleware.

Please keep in mind we have not thoroughly tested this variant and there might be some issues.

Using the proxy config only

If you're using webpack, you can import the proxy config in your webpack.config file directly by importing getProxyConfig from @twilio/flex-ui-dev-proxy. This function takes an optional serviceUrl: string argument and return a proxy config object compatible with http-proxy-middleware package.

Please keep in mind we have not thoroughly tested this variant and there might be some issues.

Configuration

If you decide to change the domain or port, the proxy will not work out of the box, since Flex depends on it running on http://localhost:8081. To change this, you need to set the insights.analyticsUrl configuration key in your appConfig.js to the correct proxy host and port.