@mintlify/assistant-web

@mintlify/assistant-web

The Mintlify Assistant browser boundary provides the hosted loader, custom-trigger API, browser transport, and direct mount lifecycle. Importing the package has no browser side effects. Browser behavior begins only after calling an exported browser function or loading the hosted script.

Hosted loader

Set the public Widget ID before loading the compatible release channel:

<script nonce="YOUR_CSP_NONCE">
  window.MintlifyAssistantSettings = {
    widgetId: 'mint_widget_example',
    context: { currentPath: window.location.pathname },
    styleNonce: 'YOUR_CSP_NONCE',
    scriptNonce: 'YOUR_CSP_NONCE',
  };
</script>
<script
  type="module"
  defer
  nonce="YOUR_CSP_NONCE"
  src="https://cdn.jsdelivr.net/npm/@mintlify/assistant-web@0.0/dist/browser/embed.js"
></script>

The @0.0 channel follows the latest compatible 0.0.x patch release. Breaking browser API changes must move to a new minor channel so existing installations do not update across them.

The loader installs window.MintlifyAssistant. Every method returns a promise after the loader has run. Calls made while its lazy runtime is loading are replayed once in invocation order.

baseUrl optionally replaces the full widget API base URL. It defaults to https://api.mintlify.com/api/assistant-widget; set it only when routing the compatible Assistant API through a proxy, regional endpoint, self-hosted deployment, or local development server.

await window.MintlifyAssistant.ready;
await window.MintlifyAssistant.open({ entryPoint: 'docs-header' });
await window.MintlifyAssistant.ask('How do I authenticate?', {
  entryPoint: 'authentication-button',
});
await window.MintlifyAssistant.update({
  context: { currentPath: window.location.pathname, version: 'v2' },
});

Entry points are trimmed strings from 1 through 100 characters. Custom triggers default to custom-trigger; the maintained trigger defaults to floating-trigger.

For controls that can run before the external script executes, install the small preload stub shown in examples/plain-html.html. Its queued open, close, focus, ask, update, newThread, and destroy calls are adopted by the loader. Repeated script loads and repeated initialization with the same Widget ID remain idempotent. Call destroy() before initializing a different widget.

identityToken is optional and exchanged only for a short-lived Assistant session. Identity, session, captcha, and trust tokens are kept in memory and are not included in browser lifecycle events. update({ identityToken }) starts a fresh thread; context, theme, and trigger visibility updates preserve the current thread.

Headless browser transport

Customer-owned browser UIs can use the session and captcha adapter without installing the maintained widget:

import { ASSISTANT_CORE_API_VERSION, createAssistantCore } from '@mintlify/assistant-core';
import { createAssistantBrowserTransport } from '@mintlify/assistant-web';

const transport = createAssistantBrowserTransport({ widgetId: 'mint_widget_example' });
const assistant = createAssistantCore({
  transport,
  metadata: {
    surface: 'headless',
    entryPoint: 'custom-search',
    coreVersion: ASSISTANT_CORE_API_VERSION,
  },
});

The adapter refreshes its short-lived session after expiry or authorization failure. It does not expose the fetch implementation or identity token through this public factory. Pass baseUrl to use a compatible API endpoint other than the production default.

Content Security Policy

Allow the following origins when the corresponding CSP directives are present:

• script-src: https://cdn.jsdelivr.net, https://challenges.cloudflare.com, and https://js.hcaptcha.com
• connect-src: https://api.mintlify.com, https://challenges.cloudflare.com, and https://*.hcaptcha.com
• frame-src: https://challenges.cloudflare.com and https://*.hcaptcha.com
• style-src: https://cdn.jsdelivr.net plus the nonce passed as styleNonce for the widget's isolated inline base styles

Replace YOUR_CSP_NONCE with the request's nonce. A strict script-src policy must authorize the inline settings/preload block itself with the <script nonce> attribute; scriptNonce only propagates that value to dynamically loaded captcha scripts. The external loader may be authorized by its host or a nonce. Pass the same value as styleNonce when style-src requires a nonce for the widget's isolated inline base styles.

Browser errors include a stable code, retryable, and optional HTTP status, plus CSP guidance for blocked runtime, API, or captcha resources. When using baseUrl, allow its origin in connect-src instead of https://api.mintlify.com.

Browser artifacts

yarn build emits the versioned dist/browser/embed.js loader and a lazy dist/browser/runtime-[hash].js runtime. Renderer assets use relative hashed paths under dist/browser/assets. The build fails if browser JavaScript contains bare host-resolved imports or if the loader reaches 8 KiB gzip. Exact byte counts are written to dist/browser/size-report.json.