0.0.26 • Published 2h ago

@mintlify/assistant-widget

Licence

Elastic-2.0

Version

0.0.26

Deps

Size

2.3 MB

Vulns

Weekly

Summary Dependency Versions

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

Load the compatible release channel and pass a normal settings object to init:

<script
  type="module"
  nonce="YOUR_CSP_NONCE"
  src="https://cdn.jsdelivr.net/npm/@mintlify/assistant-widget@0.0/dist/browser/embed.js"
></script>
<script type="module" nonce="YOUR_CSP_NONCE">
  await window.MintlifyAssistant.init({
    widgetId: 'mint_widget_example',
    theme: 'system',
    styleNonce: 'YOUR_CSP_NONCE',
    scriptNonce: 'YOUR_CSP_NONCE',
    onError(error) {
      console.error('Mintlify Assistant failed to initialize', error);
    },
  });
</script>

This snippet can be placed in either <head> or <body>. Module scripts are deferred by default, so the loader and adjacent initialization block run in document order after parsing; adding a defer attribute to type="module" does not change that behavior. Keep the initialization block after the loader, or otherwise wait for the loader's load event before calling init(settings). The Widget never requires a render-blocking script or a settings script in <head>.

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 in an idle state. Calling init(settings) starts its lazy runtime; every API method returns a promise. Calls made before initialization or while the runtime is loading are replayed once in invocation order. Passing the settings object directly preserves callback functions and does not require JSON serialization.

See the plain HTML, Next.js, and browser bundler examples for equivalent setup in different hosts. The Next.js example uses the default loading strategy; optional lazy loading delays when the Widget API becomes available.

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.

Theme

Set theme during initialization so the Widget uses the correct appearance from its first render:

light keeps the Widget light, regardless of the visitor's operating-system preference.
dark keeps the Widget dark, regardless of the visitor's operating-system preference.
system, or omitting theme, follows prefers-color-scheme and updates when that preference changes.

A fixed-theme host only needs the initialization setting. If the host can switch themes after the Widget mounts, call update({ theme }) from the host's existing theme-change handler; the Widget updates without starting a new thread.

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({
  theme: 'dark',
});

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 init, 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; theme updates preserve the current thread.

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 initialization or preload block itself with the <script nonce> attribute; scriptNonce only propagates that value to dynamically loaded captcha scripts. A static external loader may be authorized by its host or a nonce, while a dynamic import() must be permitted by script-src. 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.