esbuild OS Notifier Plugin

1.1.1 verified Fri May 01 auth: no javascript

esbuild-os-notifier (v1.1.1) is a plugin for esbuild that triggers native OS notifications when builds finish, error, or warn. It wraps node-notifier to support macOS, Windows, and Linux. Allows customization of notification content, sound, timeout, and selective enabling of success/error/warning alerts. Currently stable with monthly releases. Differentiators: minimal config, built-in TypeScript types, and simple API compared to alternatives like esbuild-plugin-notify.

Common errors

error TypeError: esbuildOsNotifier is not a function ↓

cause Importing named export instead of default.

fix

Use default import: import esbuildOsNotifier from 'esbuild-os-notifier'

error Cannot find module 'node-notifier' ↓

cause Missing peer dependency node-notifier.

fix

Install it: npm install node-notifier

error error TS2339: Property 'esbuildOsNotifier' does not exist on type 'typeof import(...)' ↓

cause Trying to import as named export instead of default.

fix

Use import esbuildOsNotifier from 'esbuild-os-notifier'

Warnings

gotcha The plugin does not forward esbuild's result object; you cannot access build results inside the notification callback. ↓

fix Use separate esbuild hooks if you need result handling.

deprecated node-notifier v10+ removed support for some Linux notification backends; upgrades may break on older Linux distributions. ↓

fix Pin node-notifier to v9 if needed, or test on your target systems.

gotcha Passing options incorrectly (e.g., nested object order) can cause TypeScript errors. ↓

fix Use the correct signature: esbuildOsNotifier(notificationOptions, eventOptions).

gotcha The plugin does not work in non-interactive environments (e.g., CI) where desktop notifications are absent. ↓

fix Wrap plugin conditionally with an environment check.

Install

npm install esbuild-os-notifier

yarn add esbuild-os-notifier

pnpm add esbuild-os-notifier

Imports

default

wrong

import { esbuildOsNotifier } from 'esbuild-os-notifier'

correct

import esbuildOsNotifier from 'esbuild-os-notifier'

Default export, not named. CommonJS require works as shown.

default (require)
```
const esbuildOsNotifier = require('esbuild-os-notifier')
```
CommonJS usage. Returns the default export.

esbuildOsNotifier (type)

wrong

import { EsbuildOsNotifierOptions } from 'esbuild-os-notifier'

correct

import type { EsbuildOsNotifierOptions } from 'esbuild-os-notifier'

Type is exported for TypeScript usage with import type.

Quickstart

Initializes esbuild with the OS notifier plugin, triggering a desktop notification on build completion or failure.

import { build } from 'esbuild';
import esbuildOsNotifier from 'esbuild-os-notifier';

build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  bundle: true,
  plugins: [esbuildOsNotifier()],
}).catch(() => process.exit(1));