Reference

Browser builds

Use the browser registry, the package subpath, or the standalone window.Notify build correctly.

Notify has three related browser-facing forms. They share a NotifyApi shape but differ in loading and side effects.

FormInstalls window.NotifyAuto-mountsIntended use
browser from @samline/notifynonoBundled apps that want one registry object
Default and named browser from @samline/notify/browsernonoDedicated bundler subpath
dist/browser/notify.global.jsyes, in a DOMyes, onceClassic script-tag usage without a bundler

The registry shape

The module registries and the resolved standalone registry expose the same six members:

interface NotifyApi {
  toast: typeof toast
  Toaster: (options?: ToasterOptions) => ToasterController
  createToaster: (options?: ToasterOptions) => ToasterController
  configureToaster: (options?: ToasterOptions) => ToasterController
  getToaster: () => ToasterController | null
  destroyToaster: () => void
}

resetToasts is a root export of the package, but it is not a member of the browser registry. Import it from @samline/notify when you need it.

Root registry

import { browser } from '@samline/notify'
import '@samline/notify/style.css'

browser.createToaster({ position: 'bottom-right' })
browser.toast.success('Saved')

The root browser export shares the same state and singleton as the named root exports. It does not install a global and it does not auto-mount.

Browser subpath

import notify, { browser } from '@samline/notify/browser'
import '@samline/notify/style.css'

notify.createToaster()
browser.toast.info('Both names refer to the same registry')

The subpath exports browser as both its default and its named export, and exports the NotifyApi type. It does not include the stylesheet and it does not mount automatically.

Standalone build

The standalone file dist/browser/notify.global.js is a built artifact, not the @samline/notify/browser module export. Load the stylesheet separately, then load the script.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Notify browser example</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/style.css"
    />
  </head>
  <body>
    <button id="notify" type="button">Show notification</button>

    <script src="https://cdn.jsdelivr.net/npm/@samline/notify@5.0.1/dist/browser/notify.global.js"></script>
    <script>
      const notify = window.Notify
      notify.configureToaster({ richColors: true, position: 'top-right' })

      document.querySelector('#notify').addEventListener('click', () => {
        notify.toast.promise(
          () => new Promise(resolve => window.setTimeout(() => resolve('ready'), 700)),
          {
            loading: 'Saving changes',
            success: 'Changes saved',
            error: 'Could not save changes',
          }
        )
      })
    </script>
  </body>
</html>

Do not combine a deferred external script with an immediately executing classic inline script: the inline script runs during parsing, before the deferred file. If the scripts must stay in the head, wait for DOMContentLoaded in your own script, or use a module script whose imports establish the ordering.

Pin a published version in production, and keep the script and the stylesheet on the same version.

The global is the registry

window.Notify is the registry itself, with the six members listed above:

window.Notify.toast.success('Ready')

Versions 3.2.0 and earlier assigned the module namespace instead; on those, resolve window.Notify.default ?? window.Notify once.

Standalone lifecycle

When the standalone build is evaluated in a browser, it assigns window.Notify. It mounts immediately if document.body exists, and otherwise it mounts once on DOMContentLoaded.

The automatic mount happens only during the initialization of the script. After Notify.destroyToaster(), or after Notify.getToaster().destroy(), call Notify.createToaster() again before sending more visible notifications.

const notify = window.Notify
notify.destroyToaster()

// Later, remount explicitly.
notify.createToaster({ position: 'bottom-left' })
notify.toast.success('Mounted again')

Server-side safety

Importing the root entrypoint or the @samline/notify/browser registry does not access the DOM. The calls that mount are DOM-only and must run in client lifecycle code.

The standalone build checks for a DOM before it does anything. In a runtime without a DOM it does not install a global and it does not mount. A server-side evaluation does not arrange a later client mount either: the browser has to load or hydrate the client entry separately.

Hosting and base paths

The CDN examples use absolute URLs, so an application base path such as /notify/ does not affect them. When self-hosting, resolve both files through your own public base:

<link rel="stylesheet" href="/my-app/vendor/notify/style.css" />
<script src="/my-app/vendor/notify/notify.global.js"></script>

Verify those URLs directly in production. A missing stylesheet leaves a semantic but visually unstyled list. A missing script leaves window.Notify undefined.

Content Security Policy

Prefer self-hosted assets under a strict policy. Otherwise allow the chosen CDN in both script-src and style-src. Inline examples also require a nonce or a hash, or an external application script.

The renderer creates inline style declarations for layout and custom properties, so a policy that blocks style attributes may require a change to the policy or a custom integration. The unstyled option disables the built-in toast presentation but does not stop the renderer layout declarations.

TypeScript global declaration

import type { NotifyApi } from '@samline/notify'

declare global {
  interface Window {
    Notify?: NotifyApi | { default: NotifyApi; Notify: NotifyApi; browser: NotifyApi }
  }
}

Check window.Notify when third-party script loading can fail. For the behavior of each member, see the API reference.