@connectdomain/widget

Let your customers connect their own domain to your product in minutes.

Drop in a single script tag (or npm install) and your users get a guided modal that:

1. Detects where their domain's DNS is hosted as they type it.
2. Configures the records for them automatically when you hold a delegated DNS credential — or shows the exact records to copy-paste when you don't.
3. Watches propagation and confirms when the domain is live.
4. Secures it with an HTTPS certificate issued automatically at the edge.
5. Optionally sets up email (MX / SPF / DKIM / DMARC) for Google Workspace, Microsoft 365, or Zoho.

It renders entirely inside a Shadow DOM, so your page's CSS can't leak in and the widget's styles can't leak out. Zero runtime dependencies for the vanilla build; React is an optional peer dependency.

Part of Connect Domain — an open-source, self-hostable custom-domain platform. This package is the browser client of its /v1 API.

Install

CDN — nothing to build:

<script src="https://connectdomain.app/sdk/v1/connectdomain.js"></script>

npm — for bundlers and frameworks:

npm install @connectdomain/widget

How authentication works

Everything the widget does is authorized by a short-lived token (a JWT, ~60 min) that your backend mints from POST /v1/tokens using your secret API key.

Never put your API key in the browser. Mint the token server-side, hand it to the page, and pass it to the widget. Tokens can be scoped to a single domain, so even if one leaks it can only act on that one hostname.

Browser ──▶ your backend  ──▶  POST /v1/tokens (Authorization: Bearer sk_live_…)
        ◀── { token }     ◀──  { auth_token, expires_at }
Browser ──▶ widget.open({ applicationId, token })

Quick start

CDN / vanilla JS

<button id="connect">Connect your domain</button>
<script src="https://connectdomain.app/sdk/v1/connectdomain.js"></script>
<script>
  document.getElementById('connect').onclick = async () => {
    // Fetch a fresh token from YOUR backend (which calls POST /v1/tokens).
    const { application_id, token } = await fetch('/api/connect-domain-token', {
      method: 'POST',
    }).then((r) => r.json());

    window.connectdomain.open({
      applicationId: application_id,
      token,
      brandName: 'Acme',
      email: true, // optional: offer email setup after the domain connects
      onSuccess: (r) => console.log('live:', r.domain),
      onClose: (r) => console.log('closed, succeeded =', r.succeeded),
    });
  };
</script>

Any bundler (ESM)

import { open } from '@connectdomain/widget';

open({ applicationId, token, brandName: 'Acme', email: true });

React

import { useConnectDomain } from '@connectdomain/widget/react';

function ConnectDomainButton({ applicationId }: { applicationId: string }) {
  const { open } = useConnectDomain({ applicationId, brandName: 'Acme', email: true });

  async function connect() {
    const { token } = await fetch('/api/connect-domain-token', { method: 'POST' })
      .then((r) => r.json());
    open({ applicationId, token });
  }

  return <button onClick={connect}>Connect your domain</button>;
}

open() has a stable identity across renders, and react is an optional peer dependency — the package works without it.

The flow your users see

| Step | What happens | | --- | --- | | Enter domain | Skipped if you pass domain. | | Analyze | Detects the DNS provider, setup path, and any conflicting records. | | Configure | Automatic providers get a one-click confirm; others get copy-paste records. | | Propagate | Polls until every record resolves, then shows success. | | Secure | A TLS certificate is issued for the domain automatically. | | Email (optional) | Pick a mailbox provider; the safe records are written and the SPF record is shown to add manually. |

Options

| Option | Type | Description | | --- | --- | --- | | applicationId (required) | string | Your application's UUID. | | token (required) | string | The short-lived token from POST /v1/tokens. | | domain | string | Pre-fill the domain and skip the first screen. | | brandName | string | Shown in the header. Defaults to "your app". | | email | boolean | Offer an email-setup step once the domain connects. | | theme | object | White-label the modal (see below). | | baseUrl | string | Control-plane origin. Defaults to https://api.connectdomain.app. | | onSuccess | (r) => void | Called with { id, domain } when the domain goes live. | | onClose | (r) => void | Called with { id, domain, succeeded } when the modal closes. |

Email setup

With email: true, after the domain connects the user can choose their mailbox provider (Google Workspace, Microsoft 365, or Zoho). The widget previews the MX / SPF / DKIM / DMARC records — warning that MX changes replace existing mail routing — then writes the ones it safely can via your delegated credential and shows the apex SPF record to add manually (so it never overwrites an existing one).

White-label theming

window.connectdomain.open({
  applicationId, token,
  theme: {
    accentColor: '#0ea5e9',     // buttons + progress
    accentTextColor: '#ffffff',
    background: '#ffffff',
    foreground: '#111827',
    radius: '10px',
    logoUrl: 'https://cdn.acme.com/logo.svg', // header logo
    hideBranding: true,          // remove the footer credit
  },
});

Theme values are applied as CSS custom properties on the widget's shadow host, so they never affect the rest of your page.

Events

Besides the onSuccess / onClose callbacks, the widget dispatches window CustomEvents you can listen to from anywhere. Each event.detail carries jobId (the connection id, which is also the id in your webhooks).

| Event | Fires | event.detail | | --- | --- | --- | | connectdomain:step | on every screen change | { domain, provider, step, jobId } | | connectdomain:success | when the domain reaches live | { domain, success, setupType, provider, jobId } | | connectdomain:close | when the modal closes | { domain, success, setupType, provider, lastStatus, jobId, reason } |

window.addEventListener('connectdomain:success', (e) => {
  analytics.track('domain_connected', { domain: e.detail.domain });
});

Accessibility & responsive

• role="dialog" + aria-modal, labelled by the current heading; a focus trap keeps keyboard focus inside the modal and returns it to the trigger on close.
• Esc opens a "leave setup?" confirmation instead of closing abruptly; a polite live region announces screen changes and copy feedback.
• 44px touch targets, visible focus rings, and prefers-reduced-motion support.
• Under 640px it becomes a safe-area-aware bottom sheet; honors prefers-color-scheme for dark mode.

Framework & SSR notes

The . and ./react entry points do not touch window at import time, so they're safe to import in server components and SSR frameworks (Next.js, Remix, etc.). The modal only mounts when you call open() in the browser.

Build & release

npm install        # dev tools only (esbuild, typescript)
npm run build      # dist/widget.js (CDN) + index.mjs + react.mjs + .d.ts
npm run typecheck

Push a widget-v* tag to publish to npm via CI (the workflow checks the tag matches package.json):

git tag widget-v1.1.0 && git push origin widget-v1.1.0

License

MIT © EVERJUST