Dynamic Flow Web Client

This is the Dynamic Flow web client. It provides a simple way to integrate a Dynamic Flow into your web app.

⚡ Access the latest deployed version of the Dynamic Flow Playground.

Integration

1. Install @wise/dynamic-flow-client.

``


yarn

yarn add @wise/dynamic-flow-client

npm

npm install @wise/dynamic-flow-client

pnpm

pnpm install @wise/dynamic-flow-client
`

2. Install required peer dependencies (if not already installed). Please refer to setup instructions for @transferwise/components and @transferwise/neptune-css if installing up for the first time.

`


yarn

yarn add react react-dom react-intl
yarn add @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css

npm

npm install react react-dom react-intl
npm install @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css

pnpm

pnpm install react react-dom react-intl
pnpm install @transferwise/components @transferwise/formatting @transferwise/icons @transferwise/neptune-css
`
Note: Keep in mind that some of these dependencies have their own peer dependencies. Don't forget to install those, for instance: @transferwise/components needs @wise/art and @wise/components-theming.

3. In addition to the design system styles, you need to import the DynamicFlow styles once into your application. You can do this either via JavaScript or CSS.

`js
import '@wise/dynamic-flow-client/main.css'; // JavaScript
`

`css
@import url('@wise/dynamic-flow-client/build/main.css'); / CSS /
`

The DynamicFlow component must be wraped in a Neptune Provider to support localisation, a ThemeProvider to provide theming, and a SnackbarProvider to ensure snackbars display correctly. Translations should be imported from both components and dynamic flows, merged, and passed to the Provider component (as below).

$3

`js
import {
Provider,
SnackbarProvider,
translations as dsTranslations,
} from '@transferwise/components';
import { getLocalisedMessages } from '@transferwise/crab/client';
import {
DynamicFlow,
translations as dfTranslations,
} from '@wise/dynamic-flow-client';

const messages = getLocalisedMessages(locale, [dsTranslations, dfTranslations])

return (







);
`

$3

You'll need to merge the '@transferwise/components' translations with the '@wise/dynamic-flow-client' translations.

`js
import {
Provider,
SnackbarProvider,
translations as dsTranslations,
} from '@transferwise/components';
import {
DynamicFlow,
translations as dfTranslations,
} from '@wise/dynamic-flow-client';

// create your messages object
const messages: Record = {
...(dsTranslations[lang] || dsTranslations[lang.replace('-', '_')] || dsTranslations[lang.substring(0, 2)] || {}),
...(dfTranslations[lang] || dfTranslations[lang.replace('-', '_')] || dfTranslations[lang.substring(0, 2)] || {}),
}

return (







);
`

Configuring your Flow

DF can be initialised with initialAction (recommended) or with an initialStep.

`tsx
initialAction={{ method: 'GET', url: '/my-amazing-new-flow' }}
httpClient={(...args) => fetch(...args)}
onCompletion={(result) => {
console.log('Flow exited with', result);
}}
onError={(error, statusCode) => {
console.error('Flow Error:', error, 'status code', statusCode);
}}
/>
`

$3

In some cases you may want to obtain the initial step yourself, and then pass it to DF component. In these cases you don't provide a initialAction since the next steps will result from interactions in the provided initialStep:

`tsx
initialStep={myInitialStep}
httpClient={...}
onCompletion={...}
onError={...}
/>
`

$3

You must pass a httpClient function. This can be window.fetch itself or some wrapper function where you inject authorisation headers and anything else you many need.

You can take advantage of the provided makeHttpClient utility function. This function takes baseUrl and additionalHeaders arguments. The baseUrl will be prefixed to any relative request URLs. Absolute URLs will not be altered. The additionalHeaders parameter can be used to add any request headers you need in all requests.

`tsx
import { makeHttpClient, DynamicFlow } from '@wise/dynamic-flow-client';

const myHttpClient = makeHttpClient('/my-base-url', { 'X-Access-Token': 'an-access-token' });

initialAction={{ method: 'GET', url: '/flow-starting-url' }}
httpClient={myHttpClient}
onCompletion={...}
onError={...}
/>
`

#### Custom httpClient functions

If you want to write your own httpClient function (or if you're writing mocks), it's important that you return actual Response objects, and that you do not throw. Errors should result in a response with an error status code and potentially a body with an error message. For example:

`tsx
const mockHttpClient = (input, init) => {
switch (input) {
case '/standard':
return Promise.resolve(new Response(init.body));
case '/exit':
return Promise.resolve(new Response(init.body, { headers: { 'x-df-exit': true } }));
case '/error':
default:
return Promise.resolve(new Response('An error has occurred.', { status: 500 }));
}
};
`

Also, please make sure your mocks return a new Response instace every time. This is because responses are mutated when we parse their body, and they cannot be parsed a second time.

`ts
const initialResponse = new Response(JSON.stringify(initialStep));
// ❌ wrong - the same instance is returned on each request
const mockHttpClient = (input, init) => Promise.resolve(initialResponse);
`

`ts
// ✅ correct - a new instance is returned on each request
const mockHttpClient = (input, init) => Promise.resolve(new Response(JSON.stringify(initialStep)));
`

$3

The DynamicFlow component accepts two optional props: onEvent and onLog which can be used to track and log.

In the example below we send tracking events to Mixpanel and logging events to Rollbar.

`tsx
onEvent={(event, props) => mixpanel.track(event, props)}
onLog={(level, message, extra) => Rollbarlevel}
/>
`

Alternatively, you can log to the browser console:

`ts
onEvent={(event, props) => console.log(event, props)}
onLog={(level, message, extra) => {
const levelToConsole = {
critical: console.error,
error: console.error,
warning: console.warn,
info: console.info,
debug: console.log,
} as const;
levelToConsolelevel;
}}
`

Contributing

We love contributions! Check out CONTRIBUTING.md` for more information.