@extend-chrome/notify

@extend-chrome/notify

This is a simpler API for chrome.notifications to use in Chrome extensions.

Add the notifications permission and create a notification with as little as a string. @extend-chrome/notify will do the rest! ✨

notify('This is too easy')

Table of Contents

• Getting Started
• Usage
• Features
• API

Getting started

You will need to use a bundler like Rollup or Webpack to include this library in the build of Chrome extension.

See rollup-plugin-chrome-extension for an easy way use Rollup to build your Chrome extension!

Installation

$ npm i @extend-chrome/notify

Usage

import { notify } from '@extend-chrome/notify'

notify('The most simple notification').then((id) => {
  console.log('notification id', id)
})

notify
  .create({
    message: 'You have been notified.',
  })
  .then((id) => {
    console.log('notification id', id)
  })

The function notify.create takes any of the official notification options for chrome.notifications.create, without trying to type "notifications" every time.

Permissions

The "notifications" permission must be included in manifest.json.

// manifest.json
{
  "permissions": ["notifications"]
}

Features

TypeScript Definitions

TypeScript definitions are included, so no need to install an additional @types library!

Gets Name and Icon from manifest.json

This library will use chrome.runtime.getManifest() to include the name and icon of your extension in your notifications!

API

notify(message: string)

Returns: Promise<string>

Create a simple notification with an icon and the name of the Chrome extension, if they are supplied in manifest.json.

Returns a promise which resolves to the notification id, which you can use in the notify.onClick and notify.onButtonClick events.

const myId = await notify('This is my notification')

notify.onClicked.addListener((clickedId) => {
  if (myId === clickedId) {
    console.log('My notification was clicked.')
  }
})

notify.create(options: NotificationOptions)

Returns: Promise<string>

Create a basic notification by default using as little as options.message, or any of the other properties in NotificationOptions.

Returns a promise which resolves to the notification id, which you can use in notification events.

const myId = await notify.create({
  message: 'This is my notification',
})

notify.onClicked.addListener((clickedId) => {
  if (myId === clickedId) {
    console.log('My notification was clicked.')
  }
})

Other methods and events

All the other methods and events from chrome.notifications are promisified using chrome-promise and assigned to notify, so you can use notify as if it is chrome.notifications with promises. These include the following:

Methods

Methods return promises but are otherwise the same as the Chrome API.

notify
  .update('my-notification', updateOptions)
  .then((wasUpdated) => {
    if (wasUpdated) {
      console.log('my notification was updated')
    }
  })

• update(id) => Promise<wasUpdated: boolean>
• clear(id) => Promise<wasCleared: boolean>
• getAll() => Promise<notificationIds: string[]>
• getPermissionsLevel() => Promise<'granted'|'denied'>

Events

Events are exacly the same as the Chrome API. Register a listener by calling addListener on an event:

notify.onClosed.addListener((id) => {
  console.log('This notification was closed', id)
})

• onClosed
• onClicked
• onButtonClicked
• onPermissionLevelChanged
• onShowSettings