desktop-notifications

A simple and opinionated library for working with OS notifications

Goals

• zero dependencies
• good support for Windows notifications
• leverage TypeScript declarations wherever possible

Note: This is currently in preview, with support for features that GitHub Desktop uses.

Install

$ npm install --save desktop-notifications
# or
$ yarn add desktop-notifications

But Why?

The current set of options for interacting with notifications, especially on Windows, have some limitations that meant we couldn't use them easily in GitHub Desktop:

• electron doesn't support Windows notifications when those are hidden away in the Action Center, because it doesn't have a COM activator that could leverage CLSID-based activation. More details about this can be found in electron/electron#29461.
• node-notifier relies on snoretoast to handle notifications on Windows, and the way it's used is only able to detect one event with each notification, and also requires the app to use the same CLSID that is hardcoded in snoretoast.
• electron-windows-notifications has many dependencies around NodeRT which, as of today, also require some manual steps in order to build them.

After exploring all these options, we decided to write our own library to do the stuff we require using no dependencies at all and having all the features we need.

Building and running the sample app

In order to get the sample app up and running you need to:

1. Build desktop-notifications.
2. Build the sample app.
3. (macOS only) Sign the Electron binary, so that macOS will allow the sample app to display notifications.
4. Start the sample app.

These are the commands to make that happen:

$ yarn install
$ yarn build
$ cd sample-app
$ yarn install
$ yarn build
$ /usr/bin/codesign --deep --force --sign - --timestamp\=none node_modules/electron/dist/Electron.app/Contents/MacOS/Electron # macOS only
$ yarn start

Documentation

See the documentation under the docs folder.

Supported versions

Each release of desktop-notifications includes prebuilt binaries based on N-API, with support for different versions of Node and Electron. Please refer to the N-API version matrix and the release documentation for Node and Electron to see what is supported currently.

Contributing

Read the Setup section to ensure your development environment is setup for what you need.

This project isn't about implementing a 1-1 replication of any other notifications API, but implementing just enough for whatever usage GitHub Desktop needs.

If you want to see something supported, open an issue to start a discussion about it.