About The Project

In Manifest V3, the Chrome extension platform moves from background pages to service workers. When migrating to this new background context, you'll need to keep two main things in mind:

• Service workers have a short life and are automatically closed when not in use
• Service workers don't have access to DOM.

Without having access (directly) to DOM, any type of operations with the intent of modify it is tedious and not straightforward. That's why Bens comes to your aid. Directly from your service worker, you can:

• Display overlay popups
• Display notifications with a high degree of flexibility and customization.

Built With

Typescript, rollup on top of Chrome Extension API (Manifest V3).

Getting Started

Prerequisites

You should use this package in the context of Chrome extension.

• npm

  npm install npm@latest -g

• tabs, scripting permissions inside manifest.json

  "permissions": [
    ...
    "tabs",
    "scripting",
    ...
  ],

Installation

Install NPM package

npm install @fvastu/bens

...and you are ready to go!

Preview

This is what you will get by default, using the light theme

Usage

After import bens, you will have to just invoke createModal giving as input a configuration object and an id of the tab where you want to show the overlay. Your code should look like something like this:

import { createModal } from '@fvastu/bens'

// Retrieve all tabs using chrome API, then pick the first one
const tab = await chrome.tabs.query({})[0];

// Show modal in the tab chosen
createModal(
    {
      theme: 'light',
      blurBackground: true,
      useAnimation: true,
      logo: 'https://svgshare.com/i/pKb.svg',
      text: "Please leave a star!",
      subtext: 'Would you mind sparing some feedback?',
      buttonContent: 'Confirm',
      cancelContent: 'Cancel',
      onConfirmClick: () => console.log('buttonConfirm Clicked'),
      onCancelClick: () => console.log('buttonCancel Clicked'),
      onOpen: () => console.log('Popup Open'),
      onClose: () => console.log('Popup Closed'),
    },
    tab.id
)

API

The function createModal accepts an object with the following parameters:

| name | type | description | default | must? | | ------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | | text | string | Primary text shows in bold with the "main" message | "" | required | | subtext | string | Secondary text shown under the primary text | "" | optional | | logo | string | URL to the logo | "" | optional | | theme | string | "dark" | "light" | "light" | optional | | useAnimation | boolean | Show a fadeIn animation when the overlay is shown | true | optional | | blurBackground | boolean | Blur the background when the overlay is shown | true | optional | | hideAfter | number | Hide the overlay after a the provided amount. N.B. if the delay is too big (e.g. greater than 30 seconds) there could be problems due to SW change to idle states. | don't hide | optional | | buttonContent | string | Label shown inside the confirm button | "" | optional | | cancelContent | string | Label shown inside the cancel button | "" | optional | | onConfirm | fn: void | function that get's executed when the user clicks on confirm button (left button). | do Nothing | optional | | onCancel | fn: void | function that get's executed when the user clicks on cancel button (right button) | do Nothing | optional | | onOpen | fn: void | function that get's executed when the modal is opened, this can be useful for things like adding body-padding, sending stats to a server etc. | do Nothing | optional | | onClose | fn: void | function that get's executed when the modal is closed, this can be useful for things like removing body-padding, etc. | do Nothing | optional |

Roadmap

• [x] Add overlay popup
• [x] Dark and light theme for overlay popup
• [ ] Add notifications popup
• [ ] Dark and light theme for notifications popup
• [ ] Add additional Templates and animation
• [ ] Improve styles injection to easily personalize the UI

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

You can write me when you want! - linkedin - [email protected]

Project Link: https://github.com/fvastu/bens

Acknowledgments

Some helpful links:

• Manifest V3
• Tabs API