@duffel/components

This package is a component library to help you build your travel product using the Duffel API.

Getting started

There are 3 different ways to integrate the components into your website. This will depend on which technology you are using. We'll use the ancillaries component as an example, but the same steps will apply for other components.

Integrating React component

1. Install the package:

   yarn add @duffel/components
   # -- or --
   npm i @duffel/components

2. Import the component from @duffel/components

   import { DuffelAncillaries } from "@duffel/components";

3. Render the component with the desired props

   <DuffelAncillaries
     offer={offerFromYourBackend} // The offer object from your backend
     seat_maps={seatMapsFromYourBackend}
     services={["bags", "seats"]}
     passengers={[...]}
     onPayloadReady={console.log}
   />

Integrating HTML custom element

If you are not using React but still in a node environment, you can:

1. Install the package:

   yarn add @duffel/components
   # -- or --
   npm i @duffel/components

2. Import the component render function and event listeners from @duffel/components/custom-elements

   import {
     renderDuffelAncillariesCustomElement,
     onDuffelAncillariesPayloadReady,
   } from "@duffel/components/custom-elements";

3. Include the custom element in your HTML

   <duffel-ancillaries></duffel-ancillaries>

4. Call the render function with the right properties to render the custom element:

   renderDuffelAncillariesCustomElement({
     offer: offerFromYourBackend,
     seat_maps: seatMapsFromYourBackend,
     services: ["bags", "seats"],
     passengers: [...],
   });

5. Set up listeners for events triggered by the component:

   onDuffelAncillariesPayloadReady((data, metadata) => {
     console.table(data);
     console.table(metadata);
   });

Integrating custom element without node

If you are not in a node environment and can't rely on npm to install the package, we make it available through our CDN. Here's how to integrate it:

1. Include a script tag

   <!--
     Replace VERSION with the desired version.
     You can find them all on https://www.npmjs.com/package/@duffel/components?activeTab=versions
   
     Replace COMPONENT with the desired component you'd like to use.
     You can find the components available in the `./cdn-dist` directory after running `yarn build-and-publish --dry-run`
   
     For example, for the duffel ancillaries component on version 3.3.1, use:
     https://assets.duffel.com/components/3.3.1/duffel-ancillaries.js
   -->
   
   <script src="https://assets.duffel.com/components/VERSION/COMPONENT.js"></script>

2. Include the custom element tag in your HTML:

   <duffel-ancillaries></duffel-ancillaries>

3. Render the component with the required data. You can safely call this function as many times as you want, e.g., when your passenger data changes.

   const duffelAncillariesElement = document.querySelector("duffel-ancillaries");
   
   duffelAncillariesElement.render({
     offer: offerFromYourBackend,
     seat_maps: seatMapsFromYourBackend,
     services: ["bags", "seats"],
     passengers: [...],
   });

4. Listen to the 'onPayloadReady' event on the component. event.detail.data contains the payload you need to send to Duffel's API to create an order.

   const duffelAncillariesElement =
     document.querySelector("duffel-ancillaries");
   
   duffelAncillariesElement.addEventListener("onPayloadReady", (event) =>
     console.log("onPayloadReady\n", event.detail),
   );

FAQ

Are there integration guides?

• Integrating the ancillaries component into your booking flow.
• Integrating the customer card form into your checkout page.

More guides are coming soon.

Which Content Security Policy directives are required?

If your application uses a Content Security Policy (CSP), merge the following sources into your existing directives.

In production, applications that load any Duffel Components bundle using the CDN <script> tag documented above must also include https://assets.duffel.com in script-src. This requirement is independent of the Evervault sandbox requirements below.

createThreeDSecureSession

Directive	Sources	Purpose
script-src	'self' https://js.evervault.com	Loads Evervault's browser SDK for the 3DS challenge.
connect-src	'self' https://api.duffel.com https://keys.evervault.com https://api.evervault.com	Allows Duffel 3DS API calls and Evervault SDK requests.
frame-src	https://ui-components.evervault.com	Embeds Evervault's 3DS challenge UI.

DuffelCardForm

Directive	Sources	Purpose
frame-src	https://api.duffel.cards	Embeds the Duffel card form.
img-src	'self' https://assets.duffel.com	Loads the card form's hosted loading spinner.
style-src-attr	'unsafe-inline'	Allows the component's React inline style attributes.

Evervault sandbox

When testing 3DS flows with Evervault's sandbox, also merge these sources into your existing directives.

Directive	Sources	Purpose
img-src	https://sandbox-acs.evervault.com	Loads sandbox ACS challenge images.
script-src	https://sandbox-acs.evervault.com https://js.evervault.com https://ui-components.evervault.com https://assets.duffel.com	Runs scripts required by sandbox 3DS flows.
style-src	https://sandbox-acs.evervault.com https://ui-components.evervault.com https://assets.duffel.com	Loads styles required by sandbox 3DS flows.
font-src	https://sandbox-acs.evervault.com	Loads sandbox ACS challenge fonts.
frame-src	https://sandbox-acs.evervault.com https://ui-components.evervault.com https://3ds-trampoline.evervault.app	Embeds sandbox ACS and Evervault 3DS challenge frames.
connect-src	https://sandbox-acs.evervault.com https://api.evervault.com https://keys.evervault.com https://api.duffel.com https://api.duffel.cards	Allows sandbox 3DS and API requests.

Is there a runnable example?

Yes. The example folder contains the repository's single runnable example. It loads duffel-ancillaries.js from the CDN, fetches a live offer and seat maps through a local server, and renders the <duffel-ancillaries> custom element.

Configure the environment in .env.local with:

DUFFEL_API_TOKEN=...

The example defaults to production Duffel API and token proxy URLs. Override those URLs in .env.local only when you need development or staging. Run it with:

yarn run-example

Where are the other component examples?

Storybook is the complete reference for available components, important visual states, and integration types. Run it with:

yarn storybook

The runnable example intentionally stays small and focused on the CDN custom-element integration.

What components are available through npm?

The list of React components can be found in src/index.ts. If you are using custom elements, you can find all render functions and event listeners in src/custom-elements.ts.

What components are available through the CDN?

Please check entryPoints in config/esbuild.base.config.js. It lists all the components and browser functions we'll build and upload to the CDN.