DEV Community

Cover image for Testing macOS Notifications in Electron 42 During Local Development
Oleksandr Trukhnii
Oleksandr Trukhnii

Posted on

Testing macOS Notifications in Electron 42 During Local Development

#electron #osx #notifications #codesign

Electron migrated to UNNotification, and now your notifications silently fail unless the app is code-signed. Here's why — and how to fix it on your dev machine without packaging and signing on every run.

If you upgraded to Electron 42 and your macOS notifications suddenly stopped showing up, you're not doing anything wrong. The framework changed under your feet.

This is a hands-on guide. By the end you'll have:

  • A tiny Electron app that sends notifications and shows a live history of every notification and the lifecycle events it emitted (show, click, close, failed).
  • An understanding of why notifications fail with UNErrorDomain error 1.
  • A free, one-time local code-signing setup so notifications work during npm start — no packaging, no paid Apple Developer account.

The breaking change

From the Electron 42 release notes:

Behavior Changed: macOS notifications now use UNNotification API
Electron has migrated from the deprecated NSUserNotification API to the UNNotification API on macOS. The new API requires that an application be code-signed in order for notifications to be displayed. If an application is not code-signed, notifications will emit a failed event on the Notification object. (#47817)

Two consequences matter for everyday development:

  1. Code signing is now mandatory for a notification banner to appear on macOS.
  2. Failures are silent unless you listen for them. When the app isn't properly signed, the Notification object emits a failed event instead of throwing. If you don't subscribe to it, nothing happens and nothing tells you why.

During local development you typically run npm start, which launches the unsigned Electron.app from node_modules. So every notification fails — quietly.

A test harness: notifications + history

Let's build the smallest possible app that makes the behavior visible. The Notification API lives in the main process, so the renderer drives it over IPC, and the main process records a history of every attempt and its events.

main.js 

// Modules to control application life and create native browser window
const { app, BrowserWindow, Notification, ipcMain } = require('electron')
const path = require('node:path')

// In-memory log of every notification we've attempted, plus the lifecycle
// events each one emitted. On Electron 42+, macOS uses the UNNotification API
// which requires the app to be code-signed; unsigned builds emit a `failed`
// event instead of showing the banner. We record that here so it's visible.
const notificationHistory = []

let mainWindow = null

function pushHistoryEvent (id, type, detail) {
  const entry = notificationHistory.find((n) => n.id === id)
  if (!entry) return
  entry.events.push({ type, detail: detail ?? null, at: new Date().toISOString() })
  // Keep the renderer's history view in sync as events arrive.
  if (mainWindow && !mainWindow.isDestroyed()) {
    mainWindow.webContents.send('notification-history-updated', notificationHistory)
  }
}

function showNotification (options = {}) {
  const id = `${Date.now()}-${notificationHistory.length}`
  const opts = {
    title: options.title || 'Electron 42 notification',
    body: options.body || 'Testing the UNNotification API on macOS.',
    silent: Boolean(options.silent)
  }

  const entry = {
    id,
    options: opts,
    supported: Notification.isSupported(),
    createdAt: new Date().toISOString(),
    events: []
  }
  notificationHistory.unshift(entry)

  if (!entry.supported) {
    pushHistoryEvent(id, 'unsupported', 'Notification.isSupported() returned false')
    return { id, supported: false }
  }

  const notification = new Notification(opts)

  notification.on('show', () => pushHistoryEvent(id, 'show'))
  notification.on('click', () => pushHistoryEvent(id, 'click'))
  notification.on('close', () => pushHistoryEvent(id, 'close'))
  // The key Electron 42 macOS behavior: unsigned apps can't display
  // notifications via UNNotification and emit `failed` with an error string.
  notification.on('failed', (_event, error) => pushHistoryEvent(id, 'failed', String(error)))

  notification.show()
  return { id, supported: true }
}

function createWindow () {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  // IPC: send a notification and report whether it was supported.
  ipcMain.handle('show-notification', (_event, options) => showNotification(options))
  // IPC: hand the full attempt-and-event log back to the renderer.
  ipcMain.handle('get-notification-history', () => notificationHistory)

  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
Enter fullscreen mode Exit fullscreen mode

A note on the word history: Electron does not expose the macOS Notification Center's system-wide history. What we track here is the app's own log of attempts and their events — which is exactly what you need to debug the signing problem, because the failed event shows up right in the list.

preload.js

The renderer has no direct access to the Notification module, so we expose a small, safe bridge over contextBridge:

const { contextBridge, ipcRenderer } = require('electron')

// Expose a minimal, safe notification API to the renderer. The Notification
// module lives in the main process, so the renderer drives it over IPC.
contextBridge.exposeInMainWorld('notifications', {
  show: (options) => ipcRenderer.invoke('show-notification', options),
  getHistory: () => ipcRenderer.invoke('get-notification-history'),
  onHistoryUpdated: (callback) =>
    ipcRenderer.on('notification-history-updated', (_event, history) => callback(history))
})
Enter fullscreen mode Exit fullscreen mode

index.html

A simple form plus a history list:

<section id="notification-tester">
  <h2>Notification tester</h2>
  <label>Title <input id="notif-title" type="text" value="Electron 42 notification"></label>
  <label>Body <input id="notif-body" type="text" value="Testing the UNNotification API on macOS."></label>
  <label><input id="notif-silent" type="checkbox"> Silent</label>
  <button id="send-notification" type="button">Send notification</button>

  <h3>History</h3>
  <ul id="notification-history"></ul>
</section>
<script src="./renderer.js"></script>
Enter fullscreen mode Exit fullscreen mode

renderer.js

Wire the button and render the history, updating live as events arrive:

const historyList = document.getElementById('notification-history')

function renderHistory (history) {
  if (!history || history.length === 0) {
    historyList.innerHTML = '<li class="empty">No notifications sent yet.</li>'
    return
  }

  historyList.innerHTML = ''
  for (const entry of history) {
    const item = document.createElement('li')

    const title = document.createElement('div')
    title.className = 'notif-title'
    title.textContent = entry.options.title
    item.appendChild(title)

    const meta = document.createElement('div')
    meta.className = 'notif-meta'
    const events = entry.events.length
      ? entry.events.map((e) => (e.detail ? `${e.type} (${e.detail})` : e.type)).join(' → ')
      : 'no events yet'
    meta.textContent = `supported: ${entry.supported} · ${events}`
    item.appendChild(meta)

    historyList.appendChild(item)
  }
}

async function refreshHistory () {
  renderHistory(await window.notifications.getHistory())
}

document.getElementById('send-notification').addEventListener('click', async () => {
  await window.notifications.show({
    title: document.getElementById('notif-title').value,
    body: document.getElementById('notif-body').value,
    silent: document.getElementById('notif-silent').checked
  })
  refreshHistory()
})

// Live updates as the main process records show/click/close/failed events.
window.notifications.onHistoryUpdated(renderHistory)

document.addEventListener('DOMContentLoaded', refreshHistory)
Enter fullscreen mode Exit fullscreen mode

Reproducing the failure

Run the unsigned dev app:

npm start
Enter fullscreen mode Exit fullscreen mode

Click Send notification. No banner appears, and the history shows something like:

Electron 42 notification
supported: true · failed (The operation couldn't be completed. (UNErrorDomain error 1.))
Enter fullscreen mode Exit fullscreen mode

Notice supported: true. Notification.isSupported() returns true because the API is available — but the actual display fails. That's the whole trap: support and delivery are now two different things.

UNErrorDomain error 1 is UNErrorCodeNotificationsNotAllowed. The UNNotification API refused to display the notification because the running app isn't code-signed.

Why ad-hoc signing isn't enough

You might reach for the quickest fix:

codesign --force --deep --sign - node_modules/electron/dist/Electron.app
Enter fullscreen mode Exit fullscreen mode

If you inspect the bundle Electron ships with, you'll see it already carries a signature:

codesign -dv node_modules/electron/dist/Electron.app
# ... flags=0x20002(adhoc,linker-signed) ...
Enter fullscreen mode Exit fullscreen mode

That linker-signed flag is the catch. It's an automatic signature the linker applies — UNNotification does not accept it. A real ad-hoc signature (codesign --sign -) drops the linker-signed flag:

codesign -dv node_modules/electron/dist/Electron.app
# ... flags=0x2(adhoc) ...
Enter fullscreen mode Exit fullscreen mode

This does make notifications work. But ad-hoc signing has a serious drawback for daily development, which leads to the next problem.

The Keychain prompt: why a stable identity matters

After re-signing, the next launch pops up a dialog:

Electron wants to use your confidential information stored in "Electron Safe Storage" in your keychain.

This isn't from our notification code. Under the hood, Electron is Chromium, and Chromium stores an encryption key (for cookies and the safeStorage API) in the macOS Keychain under "Electron Safe Storage". Access to a Keychain item is gated by the app's code signature. When you re-sign the app, macOS sees a different identity and asks for permission again.

Here's the trap with ad-hoc signatures: they have no stable identity. Every codesign --sign - produces a new cdhash. So even if you click Always Allow, the next re-sign (say, after npm install) invalidates the Keychain ACL and the prompt returns.

The fix is to sign with a stable identity — a real certificate. Then Always Allow sticks forever, and notifications keep working across reinstalls.

You don't need a paid Apple Developer account for this. A free, self-signed code-signing certificate is enough for local development.

The fix: a free self-signed code-signing certificate

Option A — Keychain Access (GUI)

  1. Open Keychain Access.
  2. Menu: Keychain Access → Certificate Assistant → Create a Certificate…
  3. Name: Electron Dev. Identity Type: Self-Signed Root. Certificate Type: Code Signing.
  4. Create it. It lands in your login keychain, ready to use.

Option B — Command line

If you prefer to script it, generate the key and certificate with OpenSSL, import it, and trust it for code signing:

# 1. Generate a self-signed code-signing certificate
cat > /tmp/electron-dev-cert.conf <<'EOF'
[ req ]
distinguished_name = dn
x509_extensions = ext
prompt = no
[ dn ]
CN = Electron Dev
[ ext ]
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, codeSigning
basicConstraints = critical, CA:false
EOF

openssl req -x509 -newkey rsa:2048 \
  -keyout /tmp/electron-dev-key.pem -out /tmp/electron-dev-cert.pem \
  -days 3650 -nodes -config /tmp/electron-dev-cert.conf

# 2. Bundle into a .p12. Use legacy algorithms + a non-empty password,
#    otherwise macOS `security` fails with "MAC verification failed".
openssl pkcs12 -export -legacy -macalg sha1 \
  -inkey /tmp/electron-dev-key.pem -in /tmp/electron-dev-cert.pem \
  -out /tmp/electron-dev.p12 -passout pass:electron -name "Electron Dev"

# 3. Import into the login keychain, allowing codesign to use the key
security import /tmp/electron-dev.p12 \
  -k ~/Library/Keychains/login.keychain-db \
  -P "electron" -T /usr/bin/codesign

# 4. Trust the certificate for code signing
#    (macOS will prompt for your login password — approve it)
security add-trusted-cert -r trustRoot -p codeSign \
  -k ~/Library/Keychains/login.keychain-db /tmp/electron-dev-cert.pem

# 5. Clean up the private key material on disk — it lives safely in the keychain now
rm -f /tmp/electron-dev-key.pem /tmp/electron-dev.p12 \
      /tmp/electron-dev-cert.pem /tmp/electron-dev-cert.conf
Enter fullscreen mode Exit fullscreen mode

⚠️ Two gotchas the recipe above already handles:

  • Empty p12 passwords fail to import on recent macOS. Use a non-empty -passout/-P pair.
  • OpenSSL 3 defaults are incompatible with the macOS security tool. Add -legacy -macalg sha1 when exporting the p12, or you'll hit MAC verification failed during PKCS12 import (wrong password?).

Verify the identity is now valid:

security find-identity -v -p codesigning
#   1) 7495...CB11 "Electron Dev"
Enter fullscreen mode Exit fullscreen mode

Sign the dev binary and automate it

Sign the Electron.app that npm start actually runs:

codesign --force --deep --sign "Electron Dev" node_modules/electron/dist/Electron.app
Enter fullscreen mode Exit fullscreen mode

Confirm the result — note Authority=Electron Dev and flags=0x0(none) (no more linker-signed):

codesign -dvv node_modules/electron/dist/Electron.app
# Authority=Electron Dev
# flags=0x0(none)
Enter fullscreen mode Exit fullscreen mode

The signature is lost every time Electron is reinstalled, so wire it into package.json so it re-applies automatically:

{
  "scripts": {
    "start": "electron .",
    "sign:dev": "codesign --force --deep --sign \"Electron Dev\" node_modules/electron/dist/Electron.app",
    "postinstall": "node -e \"process.platform==='darwin' && require('child_process').execSync('npm run sign:dev', {stdio: 'inherit'})\""
  }
}
Enter fullscreen mode Exit fullscreen mode
  • npm run sign:dev — re-sign on demand.
  • postinstall — re-sign automatically after every npm install, and only on macOS (it's a no-op elsewhere, so it won't break Linux/Windows teammates).

Verify 

npm start
Enter fullscreen mode Exit fullscreen mode

Click Send notification. This time:

  • A notification banner appears.
  • The history shows supported: true · show (and click / close as you interact).

The Keychain prompt appears once more (because the signature changed from the previous run). Click Always Allow — and because the Electron Dev identity is now stable, it's remembered for good, surviving future npm install and npm run sign:dev runs.

You can find the complete code on GitHub.

Good luck and have fun!

Top comments (0)