Embed the SDK

Your page loads the SDK once, then mounts its element wherever the founder should see it. You need your publishable key (pk_test_... or pk_live_...) and a session route on your server.

Install

npm install @doola/js

pnpm add @doola/js

yarn add @doola/js

The package is under 1 KB gzipped, ships its TypeScript types, and works as ESM or CommonJS. It contains no UI: it loads doola’s versioned loader from js.doola.com, which mounts the iframe.

Mount

import { loadDoola } from '@doola/js';

const doola = await loadDoola({
  publishableKey: 'pk_test_your_publishable_key',

  // Called on mount, before every expiry and on Try again. Always fetch a fresh session.
  fetchAccessToken: async () => {
    const r = await fetch('/doola-session', { method: 'POST' });
    if (!r.ok) {
      // Reject with the status and doola's error code: the loader maps them to error types.
      const { code } = await r.json().catch(() => ({}));
      throw Object.assign(new Error('doola session'), { status: r.status, code });
    }
    return r.json();
  },

  // Can fire more than once, so keep it idempotent.
  onAuthError: (error) => {
    if (error.type === 'partner_session_expired') location.assign('/login');
  },

  // The founder submitted the wizard, or asked to pay again. Open your checkout.
  onFormed: ({ companyId }) => openCheckout(companyId),
});

// <div id="doola"></div> on your page
document.getElementById('doola')!.append(doola.create());

create() takes no arguments. The iframe shows the wizard, the payment screen or the dashboard depending on the customer’s state.
The element is <doola-embed>, a full-width block whose height follows its content.
Append it to mount, remove it to unmount. To show a fresh state, such as the founder’s company after payment, replace it with another doola.create(). Each call creates a separate iframe, so never append a second one beside it.

Every option is described in the client reference.

One instance per page

loadDoola() creates one SDK instance for the page, and its options are fixed by the first call.

Calling loadDoola() again with the same publishable key returns the live instance and ignores the new options, callbacks included. React StrictMode’s double invoke is therefore safe.
Calling it with a different key rejects until you call destroy().

So keep the instance outside your components, and route its callbacks to whichever screen is mounted now. One small module does both:

doola.ts

import { type Doola, loadDoola } from '@doola/js';

let formedHandler: (companyId: string) => void = () => {};
let instance: Promise<Doola> | undefined;

/** The screen that is mounted now decides what happens on submit. */
export function setFormedHandler(handler: (companyId: string) => void) {
  formedHandler = handler;
}

export function getDoola(): Promise<Doola> {
  instance ??= loadDoola({
    publishableKey: 'pk_test_your_publishable_key',
    fetchAccessToken: async () => {
      const r = await fetch('/doola-session', { method: 'POST' });
      if (!r.ok) {
        // Reject with the status and doola's error code: the loader maps them to error types.
        const { code } = await r.json().catch(() => ({}));
        throw Object.assign(new Error('doola session'), { status: r.status, code });
      }
      return r.json();
    },
    onAuthError: (error) => {
      if (error.type === 'partner_session_expired') location.assign('/login');
    },
    onFormed: ({ companyId }) => formedHandler(companyId),
  }).catch((error: unknown) => {
    instance = undefined; // let the next mount try again
    throw error;
  });

  return instance;
}

/** Call when your user signs out, never on an ordinary unmount. */
export async function signOutOfDoola() {
  const current = instance;
  instance = undefined;
  (await current?.catch(() => undefined))?.destroy();
}

Frameworks

loadDoola() runs in the browser only and rejects on the server, so call it from a client-only path.

React
Next.js
Vue

DoolaFormation.tsx

import { useEffect, useRef, useState } from 'react';
import { getDoola, setFormedHandler } from './doola';

export function DoolaFormation({ onFormed }: { onFormed: (companyId: string) => void }) {
  const container = useRef<HTMLDivElement>(null);
  const [failed, setFailed] = useState(false);

  useEffect(() => setFormedHandler(onFormed), [onFormed]);

  useEffect(() => {
    let element: HTMLElement | undefined;
    let unmounted = false;

    getDoola()
      .then((doola) => {
        if (unmounted) return;

        element = doola.create();
        container.current?.append(element);
      })
      .catch(() => setFailed(true));

    return () => {
      unmounted = true;
      element?.remove();
    };
  }, []);

  if (failed) return <p>Company formation could not load. Check your connection and try again.</p>;

  return <div ref={container} />;
}

To show the founder’s dashboard after you confirm payment, remount the component, for example by changing its key.

Mark the component as client-only and render it like the React example. The session route is a route handler.

app/formation/DoolaFormation.tsx

'use client';

// The React component from the previous tab, unchanged.

app/formation/page.tsx

import { DoolaFormation } from './DoolaFormation';

export default function FormationPage() {
  return <FormationScreen />; // a client component that renders <DoolaFormation onFormed={...} />
}

Never import @doola/js from a server component. It has nothing to do there, and loadDoola() rejects outside the browser.

DoolaFormation.vue

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue';
import { getDoola, setFormedHandler } from './doola';

const emit = defineEmits<{ formed: [companyId: string] }>();
const container = ref<HTMLDivElement>();
const failed = ref(false);
let element: HTMLElement | undefined;

setFormedHandler((companyId) => emit('formed', companyId));

onMounted(async () => {
  try {
    const doola = await getDoola();
    element = doola.create();
    container.value?.append(element);
  } catch {
    failed.value = true;
  }
});

onBeforeUnmount(() => element?.remove());
</script>

<template>
  <p v-if="failed">Company formation could not load. Check your connection and try again.</p>
  <div v-else ref="container" />
</template>

Sign out

Call destroy() when your user signs out of your product. It ends the doola session and removes every element, and the instance cannot be used again. To embed for the next user, call loadDoola() again. Never call destroy() on an ordinary unmount or route change. Remove the element instead; the session stays alive for the next mount.

Load faster

Start the connections early with two hints in your <head>:

<link rel="preconnect" href="https://js.doola.com" crossorigin />
<link rel="preconnect" href="https://sdk.doola.com" />

With test keys, point the second hint at https://sdk.test.doola.com.

Content Security Policy

If your site sends a CSP, allow the loader and the iframe:

script-src https://js.doola.com;
frame-src https://sdk.doola.com;

With test keys, also allow https://sdk.test.doola.com in frame-src. If you enforce Trusted Types, allow the doola-js policy. See Security and data.

When it cannot load

loadDoola() rejects when the SDK cannot start, so your page shows its own fallback:

It ran outside a browser, for example during server rendering.
The loader script was blocked by a CSP, an ad blocker or the network.
An option is invalid, such as a key that is not pk_test_... or pk_live_.... The message names it.

Once the iframe is running, it shows its own error screens. Pass onLoadError to log them, and see Errors for the one case where your page is the only place to tell the founder.

Get started

Integrate

Customize

Test and launch

Reference

Help

Install

Mount

One instance per page

Frameworks

Sign out

Load faster

Content Security Policy

When it cannot load

​Install

​Mount

​One instance per page

​Frameworks

​Sign out

​Load faster

​Content Security Policy

​When it cannot load

Install

Mount

One instance per page

Frameworks

Sign out

Load faster

Content Security Policy

When it cannot load