- Docs
- Browser builds
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.
| Form | Installs window.Notify | Auto-mounts | Intended use |
|---|---|---|---|
browser from @samline/notify | no | no | Bundled apps that want one registry object |
Default and named browser from @samline/notify/browser | no | no | Dedicated bundler subpath |
dist/browser/notify.global.js | yes, in a DOM | yes, once | Classic 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.