DEV Community: Ivan N

Tab Roulette - my first extension

Ivan N — Mon, 02 Dec 2024 12:12:52 +0000

My current goal is to create a simple Chrome extension that utilizes the background capabilities of the extension framework.

To recap, the background script operates as a service worker, primarily designed to handle tasks that do not require direct user interaction.

One of its key roles is to act as a communication hub or event handler, serving as the only persistent and reliable component in the browser extension architecture. Unlike content scripts, popups, or options pages, which are ephemeral, the background service worker ensures continuity by automatically restarting when terminated to handle incoming events.

I plan to leverage this capability of the background script as the central controller for my extension.

The use case

This first Chrome extension will be quite straightforward. It will listen for clicks on the extension's action icon and respond by triggering a roulette-like behavior. The roulette will sequentially activate the tabs currently open in the user's browser for a short period until one tab is randomly left selected.

As you can see, this extension doesn't serve a practical purpose but is intended purely as a learning exercise.

The manifest

{
  "name": "TabRoulette",
  "version": "0.0.1",
  "manifest_version": 3,
  "icons": {
    "16": "images/icon16.png",
    "32": "images/icon32.png",
    "48": "images/icon32.png",
    "128": "images/icon128.png"
  },
  "action": {
    "default_title": "Click to start",
    "default_icon": {
      "16": "images/icon16.png",
      "24": "images/icon24.png",
      "32": "images/icon32.png"
    }
  },
  "background": {
    "service_worker": "background.js"
  }
}

In addition to the icons specified in the manifest for use in the Chrome Web Store and extension management interface, the most significant addition is the action attribute. This attribute configures the behavior of the extension when the toolbar icon is clicked. In our case, it instructs the service worker to initiate a tab roulette upon user interaction.

To take into account
My code uses ES imports, but as shown earlier, the service_worker was not explicitly declared as a module. How did it still work?

"background": {
  "service_worker": "service-worker.js",
  "type": "module"
}

These imports are handled and resolved by Vite during the bundling process.

Background

As mentioned earlier, the background script will listen for clicks on the action icon and initiate a tab roulette in response.

chrome.action.onClicked.addListener(async () => {
 ...
})

Key aspects of the listener logic to highlight: First, I need to gather all the tabs currently open in the active window. This is essential because my code requires references to these tabs to cycle through them sequentially.

const currentWindow = await chrome.windows.getCurrent();
const windowTabs = await chrome.tabs.query({
  windowId: currentWindow.id,
});

I initially got confused when using chrome.tabs.query without specifying a windowId, as it returned all the tabs across all open browser windows, whereas I only wanted the tabs from the active window. This led to unexpected results due to the larger number of tabs in the list.

Once I understood this behavior, activating the tabs sequentially became straightforward. It simply involves updating the tab properties to set each one as active in sequence until a random tab is ultimately selected.

chrome.tabs.update(nextTab.id!, { active: true });

Another goal I wanted to achieve was to adjust the pace at which the tabs are activated—starting quickly and slowing down toward the end. To accomplish this, the native setInterval function I used in the initial test was insufficient. Instead, I implemented a small utility that allowed me to create an adjustable interval, providing a way to dynamically modify its timing as needed.

function startInterval(callback: () => void, interval: number) {
  let intervalId = setInterval(callback, interval);
  return {
    stop: () => clearInterval(intervalId),
    changeInterval: (newInterval: number) => {
      clearInterval(intervalId);
      intervalId = setInterval(callback, newInterval);
    },
  };
}

And that’s it—a simple extension with a playful use case, serving as an excuse to delve deeper into the world of browser extensions. I'm also sharing the source code with you if you're curious about the details.

Oh, and I also used this project to explore the publishing process, which I found to be quite straightforward. Now, I'm just waiting for the review and final publication.

https://github.com/ivaneffable/tabRoulette

Create a CLI to scaffold browser extensions

Ivan N — Wed, 20 Nov 2024 13:44:20 +0000

In our previous exercise, we built a browser extension using TypeScript. This involved a series of steps, including creating a Vite project and customizing it to meet the specific requirements of browser extensions. While the process wasn’t particularly lengthy or complex, we can simplify it further by automating it with a Node CLI (Command Line Interface). If you're new to CLIs, let me walk you through the one I've created!

Create a Node project

Naturally, the first step is to initialize and set up our Node project. Use the following commands to create a folder for our code and generate a basic package.json file:

mkdir create-browser-extension-vite && cd create-browser-extension-vite
npm init --yes

Next, I decided to modify the generated package.json to include "type": "module". With this we’ll inform Node to interpret .js files in the project as ES modules rather than CommonJS modules. Here's the updated package.json after making some adjustments.

{
  "name": "create-browser-extension-vite",
  "version": "1.0.0",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "publishConfig": {
    "access": "public"
  },
  "keywords": [
      "cli",
    "create-project"
  ],
  "author": "",
  "license": "ISC",
  "description": "A CLI tool to create browser extensions with Vite",
  "type": "module"
}

First steps

Let’s begin by creating a file called create-project in a new folder named bin:

#!/usr/bin/env node

console.log("hello world");

This file will act as the entry point for your command and to ensure it can be ran directly on your computer once the package is installed globally, add the following field to the package.json:

"bin": "bin/create-project"

Now it's time to test what we've built so far. First, we install the package locally by running:

npm link
create-browser-extension-vite // execute the CLI

Once linked, you’ll have a new CLI command called create-browser-extension-vite, which currently just prints “hello world” to the console.

And that’s all it takes to create a basic CLI! From here, you can leverage the full power of the Node ecosystem to build anything you can imagine.

Handling user input

Let’s take another step toward our goal! The aim of this CLI is to generate a fully functional TypeScript browser extension with a single command. To accomplish this, the CLI will accept several optional parameters.

name: If provided, a folder with the specified name will be created. Otherwise, the current folder will contain the project.
git: If specified, a Git repository will be initialized for the project.
install: If specified, the project dependencies will be installed automatically.
yes: Skips all prompts and generates the project with default settings.

The first step is to create a new file, src/cli.js, which will handle all the logic for collecting user preferences. This new module will be invoked from the current create-project file:

#!/usr/bin/env node

import { cli } from "../src/cli.js";

cli(process.argv);

To streamline the process of gathering user preferences, we’ll use two useful libraries:

npm install @inquirer/prompts arg

arg: A powerful argument parser for handling command-line inputs.
@inquirer/prompts: A library for creating elegant and interactive command-line interfaces.

import arg from "arg";
import { confirm } from "@inquirer/prompts";

async function promptForMissingOptions(options) {
  if (options.skipPrompts) {
    return options;
  }

  return {
    ...options,
    git:
      options.git ||
      (await confirm({ message: "Initialize a git repository?" })),
  };
}

function parseArgumentsIntoOptions(rawArgs) {
  const args = arg(
    {
      "--git": Boolean,
      "--help": Boolean,
      "--yes": Boolean,
      "--install": Boolean,
      "-g": "--git",
      "-y": "--yes",
      "-i": "--install",
    },
    {
      argv: rawArgs.slice(2),
    }
  );

  return {
    skipPrompts: args["--yes"] || false,
    git: args["--git"] || false,
    runInstall: args["--install"] || false,
    projectName: args._[0],
  };
}

export async function cli(args) {
  let options = parseArgumentsIntoOptions(args);
  options = await promptForMissingOptions(options);
  console.log(options);
}

I’ll leave it to you to add an extra option for displaying a basic help message. This will involve introducing a new user preference controlled by the --help or -h parameter. If this parameter is provided, the CLI should display a simple manual explaining the command’s usage. You can refer to my solution in the repository linked below.

Creating the project

In this step, the project will be created based on the preferences selected in the previous stage. We'll begin by creating a folder named template and copying into it the files that will make up the generated project.

The folder structure should look like this, and you can find the content of these files in my GitHub repository. If you’re curious about how they were created, check out my previous post, where I discuss building a browser extension with TypeScript.

Our code will utilize the files in the template folder to generate the user's new browser extension and the following packages will be particularly useful in accomplishing this:

npm install ncp chalk execa pkg-install listr

ncp: Facilitates recursive copying of files.
chalk: Adds terminal string styling.
execa: Simplifies running external commands like git.
pkg-install: Automatically triggers either yarn install or npm install based on the user's preference.
listr: Allows defining a list of tasks while providing a clean progress overview for the user.

We'll begin by creating a new file, src/main.js, to contain the code that generates the project by copying the files from the template folder.

import { createProject } from "./main.js";

...

export async function cli(args) {
  let options = parseArgumentsIntoOptions(args);
  options = await promptForMissingOptions(options);
  await createProject(options);
}

import chalk from "chalk";
import ncp from "ncp";
import path from "path";
import { promisify } from "util";
import { execa } from "execa";
import Listr from "listr";
import { projectInstall } from "pkg-install";

const copy = promisify(ncp);

async function copyTemplateFiles(options) {
  return copy(options.templateDirectory, options.targetDirectory, {
    clobber: false,
  });
}

async function initGit(options) {
  const result = await execa("git", ["init"], {
    cwd: options.targetDirectory,
  });
  if (result.failed) {
    return Promise.reject(new Error("Failed to initialize git"));
  }
  return;
}

export async function createProject(options) {
  options = {
    ...options,
    targetDirectory: options.projectName || process.cwd(),
  };

  const currentFileUrl = import.meta.url;
  const templateDir = path.resolve(
    new URL(currentFileUrl).pathname,
    "../../template"
  );
  options.templateDirectory = templateDir;

  const tasks = new Listr([
    {
      title: "Copy project files",
      task: () => copyTemplateFiles(options),
    },
    {
      title: "Initialize git",
      task: () => initGit(options),
      enabled: () => options.git,
    },
    {
      title: "Install dependencies",
      task: () =>
        projectInstall({
          cwd: options.targetDirectory,
        }),
      skip: () =>
        !options.runInstall
          ? "Pass --install to automatically install dependencies"
          : undefined,
    },
  ]);

  await tasks.run();
  console.log("%s Project ready", chalk.green.bold("DONE"));
  return true;
}

The code above utilizes Listr to execute the series of actions needed to generate the new project, from copying files with ncp to setting up the Git repository. Also note how we used promisify to convert the callback-based copy method of ncp into a promise-based function, making the code more readable and maintainable.

And that’s it! These are the steps I followed to create my new CLI tool, the one I’ll be using to streamline the creation of my new browser extensions. You can use it too! Because I’ve published it on npm for anyone to generate their own extensions.

https://github.com/ivaneffable/create-browser-extension-vite

References

How to build a CLI with Node.js

Create Browser Extension with Vite + TS

Ivan N — Sun, 10 Nov 2024 12:43:12 +0000

Let's begin this exercise focusing on setting up the most basic extension structure, one that includes just a manifest file and a service worker. The manifest acts as the configuration file, specifying what the extension is allowed to do, while the service worker handles background tasks, primarily responding to browser events, in this instance, it logs when the extension is installed.

{
  "name": "Simple",
  "version": "0.0.1",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  }
}

manifest.json

console.log("Initialized background script!");

chrome.runtime.onInstalled.addListener((object) => {
  console.log("Installed background script!");
});

background.js

The service worker can be as complex as needed, but we'll keep it straightforward for now as the goal of this task is to transform this simple two-file extension into a Vite project.

So why use Vite? Primarily because I've decided to work with TypeScript, which will significantly improve code quality, maintainability, and productivity. Beyond offering self-documentation, TypeScript allows me to catch type-related errors at compile-time rather than at runtime, enhancing the overall development experience.

Vite

Although a Node project with TypeScript would suffice to compile my TS code into the vanilla JavaScript required by my extension, I opted for Vite. Vite, especially with its Rollup bundler, offers extensive capabilities like tree-shaking and bundle minification. Additionally, Vite’s robust plugin ecosystem would allow me to easily integrate React if I decide to create UI components for the extension in the future.

With that in mind, let’s start by creating the Vite project using its vanilla-ts template.

npm create vite@latest simple-extension -- --template vanilla-ts

After running the command and installing dependencies, you’ll have a small web project set up with TypeScript. However, since this setup isn’t quite what we need, we’ll start with some cleanup. First, delete the index.html file from the root folder, as it’s not required anymore. Then, remove all files in the src folder except for vite-env.d.ts, which provides type definitions for Vite-specific features. Finally, delete everything in the public folder.

⚠️ If you encounter errors in your tsconfig file about unknown compiler options, ensure that your editor is using the same TypeScript version installed for the project.

Next, create a new file in the src folder named background.ts and copy the code from the original background.js file into it.

You’ll soon notice that TypeScript requires additional context to function properly, as it doesn’t recognize the chrome object without the appropriate types. To address this, install @types/chrome to provide the necessary type definitions for chrome.

npm i -D @types/chrome

Once installed, the TypeScript errors disappear. However, you may notice a warning message in the onInstalled callback. This is due to the linting properties that Vite has configured for us in our TypeScript setup.

/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedSideEffectImports": true

tsconfig.json

Since we’re defining an object that isn’t used, let’s go ahead and remove it. That should be all we need, so now we can compile the project.

npm run build

There seems to be an issue—the default Vite configuration is still attempting to use some of the files we just removed as the code entry point.

x Build failed in 6ms
error during build:
Could not resolve entry module "index.html".

We need to customize our Vite configuration to run in Library Mode. Here’s the minimal configuration required for this project.

import { defineConfig } from "vite";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        background: "./src/background.ts",
      },
      output: {
        entryFileNames: `[name].js`,
      },
    },
  },
});

vite.config.ts

In the configuration above, we’re simply setting the project’s input to ./src/background.ts and adjusting the output filename to [name].js. By default, Vite appends a hash to filenames for production builds (e.g., background-[hash].js), but we need an exact filename match for our manifest.json to work correctly.

Speaking of manifest.json, where should it be located? This part is straightforward: any file that should be copied as-is, without transformations, to the output folder should be placed in the public folder. Now, if we build the project again, we’ll find our two-file browser extension compiled in the dist folder.

npm run build

Installation

Let’s now verify everything is working as expected. If you haven’t tested a browser extension locally before, just follow these simple steps:

Open the Extensions page by entering chrome://extensions in a new tab.
Enable Developer Mode by toggling the Developer mode switch.
Click Load unpacked and select the extension directory, which is the dist folder generated by Vite. And that’s it! The extension is now installed. If you click on the service worker link, the DevTools for this service worker will open, where you can view the logs generated by our worker in action.

simple-vite-extension