But they usually don't tell you the next info you need as a developer: What should I ask my coding agent to change?

AI coding agents can help you fix performance issues, but they need clear context. If you type "make this site faster", you'll often get broad advice. If you give the agent the metric, the affected resource, the likely cause, and the files to inspect first, you have a much better chance of getting a useful patch.

In this tutorial, you'll learn how to turn a browser performance finding into a structured AI fix prompt. You'll also see how to add a "Copy AI fix prompt" button to a Chrome DevTools extension.

I'll use PerfLens, a Chrome DevTools extension I built, as the example. But the same pattern works with any tool that can collect performance data.

What You Will Build

You'll build a small pipeline that looks like this:

Performance finding
  -> Structured issue object
  -> AI fix prompt
  -> Clipboard
  -> Coding agent
  -> Code change
  -> Re-run audit

By the end, you will have:

• A Finding type for storing audit results

• A prompt builder function

• A copy-to-clipboard function

• A DevTools panel button that copies the generated prompt

• A simple way to verify whether the fix worked

Prerequisites

To follow along, you should understand:

• Basic JavaScript or TypeScript

• Basic browser extension concepts

• How Chrome DevTools panels work at a high level

• How to use an AI coding agent such as Cursor, Claude Code, GitHub Copilot, or a similar tool

You don't need to build a full performance auditing engine for this tutorial. The focus is the handoff between a performance tool and a coding agent.

Table of Contents

• Why Performance Reports Are Hard to Turn into Code Changes

• What an AI Fix Prompt Should Include

• How to Store a Performance Finding as Structured Data

• How to Choose the Most Important Finding

• How to Build the AI Fix Prompt

• How to Copy the Prompt to the Clipboard

• How to Add the Button to a DevTools Panel

• How to Verify the Fix

• How This Fits Alongside Lighthouse

• Conclusion

Why Performance Reports Are Hard to Turn into Code Changes

A performance score is a symptom. For example, a report might say:

Largest Contentful Paint: 4.2 seconds

That number matters, but it doesn't tell you where the fix lives.

The cause might be:

• A large hero image

• A render-blocking script

• Too much JavaScript on the initial route

• A slow API request

• Missing image dimensions that cause layout shift

As a developer, you usually have to translate the report into a code-level task.

That translation step takes time. It's also the step where a coding agent can help most, if you give it enough context.

Instead of asking your agent to "make the site faster", you can give it a focused brief:

The homepage has a 258.1 KB image affecting load performance.
Inspect the hero section and image component first.
Resize or compress the image without changing the layout.
Then explain how to verify the improvement.

This is easier for the agent to act on because it points to one specific problem.

What an AI Fix Prompt Should Include

A good AI fix prompt should read like a short engineering brief.

It should include:

• The performance problem

• The measured evidence

• The affected page or resource

• The likely cause

• The files or patterns to inspect first

• A recommended fix

• Constraints for the change

• Verification steps

Here is an example prompt:

You are helping optimize a Next.js app in a production build.

Problem: Image is 258.1 KB and may be slowing down the page.
Evidence: Image size = 258.1 KB
Page: http://localhost:3000
Affected resource: http://localhost:3000/_next/image?url=%2Fhome%2Four_story.webp&w=3840&q=75

Likely cause:
The page is loading an image that is larger than needed for its rendered size.

Inspect first:
- app/page.tsx or pages/index.tsx
- components/**/*.{tsx,jsx}
- next.config.js
- the hero section or image component

Recommended fix:
Resize or compress the image, use an appropriate modern format, and keep explicit width and height values so the layout does not shift.

Constraints:
- Keep the change local to the route or component causing the issue.
- Do not add a new dependency unless there is no reasonable alternative.
- Explain the change before applying it.

After the change:
- Re-run the performance audit.
- Confirm the image transfer size is lower.
- Confirm the layout still looks correct.

This prompt is specific. It tells the agent what happened, where to look, what to change, and how to check the result.

That's the core idea behind an AI patch brief.

Here is what that looks like inside PerfLens. A single performance finding is rendered as an AI patch brief, with the measured value, the affected resource, and the generated prompt gathered in one place. The "Copy AI fix prompt" button then hands the whole brief off to your coding agent in one click.

How to Store a Performance Finding as Structured Data

Before you can build a prompt, you need to store the performance issue as data.

Here is a simple TypeScript type:

type Finding = {
  id: string;
  title: string;
  metric: string;
  measured: string;
  budget?: string;
  resource?: string;
  likelyCause: string;
  recommendedFix: string;
  inspectFirst: string[];
  severity: "low" | "medium" | "high";
};

Each field has a job:

• id identifies the type of issue.

• title gives the human-readable summary.

• metric names the measurement.

• measured stores the actual value.

• budget stores the target value, if you have one.

• resource stores the affected URL, file, or asset.

• likelyCause explains why the issue may be happening.

• recommendedFix gives the agent a direction.

• inspectFirst points the agent toward likely files.

• severity helps you decide what to show first.

Here is an example finding for an oversized image:

const finding: Finding = {
  id: "image-weight",
  title: "Image is 258.1 KB and may be slowing down the page",
  metric: "Image size",
  measured: "258.1 KB",
  resource: "http://localhost:3000/_next/image?url=%2Fhome%2Four_story.webp&w=3840&q=75",
  likelyCause:
    "The page is loading an image that is larger than needed for its rendered size.",
  recommendedFix:
    "Resize or compress the image, use an appropriate modern format, and keep explicit width and height values.",
  inspectFirst: [
    "app/page.tsx or pages/index.tsx",
    "components/**/*.{tsx,jsx}",
    "next.config.js",
    "the hero section or image component",
  ],
  severity: "high",
};

At this stage, you aren't doing anything with AI yet. You're only turning a performance result into a clean object.

That object gives you something reliable to transform into a prompt later.

How to Choose the Most Important Finding

You should avoid sending ten unrelated performance issues to an agent at once.

A large prompt with many issues can lead to a large patch. That makes the result harder to review.

A better approach is to generate one prompt per finding.

You can start with a simple severity score:

function scoreFinding(finding: Finding): number {
  const severityWeight = {
    low: 1,
    medium: 2,
    high: 3,
  };

  return severityWeight[finding.severity];
}

Then you can sort findings by score:

function sortFindings(findings: Finding[]): Finding[] {
  return [...findings].sort(
    (a, b) => scoreFinding(b) - scoreFinding(a)
  );
}

This is a simple version, but it's enough to get started.

Later, you can improve the score by considering:

• How far the metric is over budget

• Whether the issue affects Largest Contentful Paint

• Whether the issue affects layout shift or interaction delay

• Whether the affected resource is part of the first page load

• How confident you are in the recommended fix

The goal isn't to create a perfect scoring system. The goal is to help you focus on one high-impact issue at a time.

How to Build the AI Fix Prompt

Once you have a Finding, building the prompt becomes a string formatting task.

You also need a small amount of page context:

type PageContext = {
  framework: string;
  mode: string;
  pageUrl: string;
};

Page context is a few facts about the page the finding came from: the framework the app uses, whether it's a development or production build, and the URL being audited.

The finding tells the agent what is slow. The page context tells it where the fix will land and how the code is built. This matters because the same problem is fixed differently from one stack to the next. An oversized image is handled through next/image and next.config.js in Next.js, but through other files and conventions elsewhere. The mode field also hints whether production optimizations should already be in place.

Giving the agent this up front means it spends less effort guessing about your setup and more on the actual fix.

Then you can create a prompt builder:

function buildFixPrompt(finding: Finding, ctx: PageContext): string {
  const lines = [
    "You are helping optimize a " + ctx.framework + " app in a " + ctx.mode + " build.",
    "",
    "Problem: " + finding.title,
    "Evidence: " + finding.metric + " = " + finding.measured +
      (finding.budget ? " (budget: " + finding.budget + ")" : ""),
    "Page: " + ctx.pageUrl,
  ];

  if (finding.resource) {
    lines.push("Affected resource: " + finding.resource);
  }

  lines.push(
    "",
    "Likely cause:",
    finding.likelyCause,
    "",
    "Inspect first:",
    ...finding.inspectFirst.map((file) => "- " + file),
    "",
    "Recommended fix:",
    finding.recommendedFix,
    "",
    "Constraints:",
    "- Keep the change local to the route or component causing the measured cost.",
    "- Do not add new dependencies unless there is no reasonable alternative.",
    "- Explain the change before applying it.",
    "",
    "After the change:",
    "- Re-run the performance audit.",
    "- Confirm the measured issue improved.",
    "- Check that the UI still works correctly.",
  );

  return lines.join("\n");
}

You can call it like this:

const pageContext: PageContext = {
  framework: "Next.js",
  mode: "production",
  pageUrl: "http://localhost:3000",
};

const prompt = buildFixPrompt(finding, pageContext);

The output is a prompt you can paste into a coding agent.

The framework field is especially useful. If the agent knows the app uses Next.js, it can look for files such as app/page.tsx, pages/index.tsx, next.config.js, and image usage through next/image.

How to Copy the Prompt to the Clipboard

The safest integration is clipboard-first.

Many coding agents and editors support different launch methods. Some support deep links. Some run in the terminal. Some live inside an editor. But every agent can accept pasted text.

Here's a small copy function:

async function copyPrompt(prompt: string): Promise<void> {
  await navigator.clipboard.writeText(prompt);
}

In a browser extension UI, call this from a user action such as a button click:

copyButton.addEventListener("click", async () => {
  const prompt = buildFixPrompt(finding, pageContext);

  await copyPrompt(prompt);

  copyButton.textContent = "Prompt copied";
});

You can also try to open an editor after copying the prompt:

type AgentTarget = "cursor" | "vscode" | "copy-only";

async function sendToAgent(
  prompt: string,
  target: AgentTarget
): Promise<void> {
  await navigator.clipboard.writeText(prompt);

  if (target === "cursor") {
    window.location.href = "cursor://";
    return;
  }

  if (target === "vscode") {
    window.location.href = "vscode://";
    return;
  }
}

This doesn't paste the prompt into the agent automatically. It only copies the prompt and tries to open the selected tool.

That is a useful limitation. It keeps the workflow predictable and lets you review the prompt before sending it.

How to Add the Button to a DevTools Panel

If you build this into a Chrome extension, you can expose it inside a DevTools panel.

First, register a DevTools page in your manifest.json file:

{
  "manifest_version": 3,
  "name": "PerfLens",
  "version": "1.0.0",
  "devtools_page": "devtools.html",
  "permissions": ["clipboardWrite", "activeTab", "scripting"]
}

Then create the panel from your DevTools script:

chrome.devtools.panels.create(
  "PerfLens",
  "icons/icon-32.png",
  "panel.html"
);

Inside the panel, render each finding with a button:

function renderFinding(
  finding: Finding,
  ctx: PageContext
): HTMLElement {
  const item = document.createElement("article");
  const title = document.createElement("h3");
  const button = document.createElement("button");

  title.textContent = finding.title;
  button.textContent = "Copy AI fix prompt";

  button.addEventListener("click", async () => {
    const prompt = buildFixPrompt(finding, ctx);

    await sendToAgent(prompt, "copy-only");

    button.textContent = "Prompt copied";
  });

  item.append(title, button);

  return item;
}

The important part is the button handler.

When you click the button, your extension:

1. Builds a prompt from the performance finding.

2. Copies the prompt to the clipboard.

3. Shows feedback that the prompt was copied.

You can then paste the prompt into your coding agent and review the suggested patch.

How to Verify the Fix

An AI-generated patch is only useful if the metric improves.

After the agent suggests a change, you should:

1. Review the code diff.

2. Run the app locally.

3. Reload the page.

4. Re-run the performance audit.

5. Compare the new measurement with the original one.

For the image example, you would check:

• Did the image transfer size go down?

• Does the image still look sharp enough?

• Did the page layout stay stable?

• Did Largest Contentful Paint improve?

• Did the change affect any other route?

This creates a simple loop:

Measure -> Prompt -> Patch -> Measure again

You shouldn't treat the agent's answer as the final authority. The browser measurement is the final authority.

How This Fits Alongside Lighthouse

Lighthouse is still useful. It gives you a detailed lab audit and a consistent score. This workflow solves a different problem.

Lighthouse helps you answer:

How does this page perform under controlled conditions?

An AI patch brief helps you answer:

What should I ask my coding agent to fix right now?

You can use both.

Use Lighthouse for scoring, regression tracking, and deeper audits. Use an AI prompt workflow when you want to move from a specific finding to a code change faster.

A Note on Privacy

AI fix prompts can include URLs, resource names, routes, filenames, and implementation details.

Before you paste a prompt into a cloud-based coding agent, check that it doesn't include:

• Access tokens

• Private customer data

• Internal URLs you can't share

• Secrets from environment variables

• Sensitive logs

Keep the prompt focused on the performance issue. Give the agent enough context to help, but not more than it needs.

Conclusion

In this tutorial, you learned how to turn a performance audit finding into an AI fix prompt.

You created:

• A structured Finding type

• A way to rank findings

• A buildFixPrompt function

• A clipboard-first agent handoff

• A DevTools panel button

• A verification loop for checking the result

The main idea is simple: performance tools produce evidence, and coding agents need context. A good AI patch brief connects the two.

PerfLens is one example of this workflow. If you want to try the extension or inspect how it implements this flow, you can find it here:

• Chrome Web Store: PerfLens

• Source code: GitHub

You might spend three days comparing laptops across a dozen tabs, get distracted, come back a week later, and your history just shows a flat list of timestamps and titles, with no sense that those visits were one thing, a decision you started and never finished.

In this tutorial, you'll build openloops, an open-source, local-first Chrome extension that fixes this by scanning your browsing history and grouping it into "intent threads" – the decisions, research, and open questions you keep coming back to – then scoring each one for how alive it still is. Optionally, it also uses Claude to label those threads in plain language, suggest a concrete next step, and power a chat assistant you can ask "what should I close this week?"

By the end, you'll have built:

• A Manifest V3 Chrome extension with a service worker and a full-tab dashboard

• A local pipeline that captures, cleans, segments, and clusters browsing history entirely in IndexedDB

• A clustering algorithm tuned and debugged on real (messy) browsing data

• An AI labeling layer using Claude, with a grounding step that uses brand data from context.dev

• A chat assistant that reasons across your threads and tells you what to do next

• A polished dashboard with onboarding, a design system, and a working pipeline status machine

Everything runs on-device, and the only network calls are optional and opt-in, made with your own API keys.

Table of Contents

• What You'll Build

• Prerequisites

• How openloops Is Structured

  • The shared types

  • The manifest

• How to Scaffold the Extension

• How to Capture Your Browsing History

  • A few shared helpers

  • The database layer (so far)

  • Capturing new visits live

  • Backfilling 14 days of history

  • Checkpoint

• How to Turn Noise into Sessions

  • Filtering out noise

  • Extracting keywords

  • Extending the database for sessions

  • Segmenting events into sessions

  • Checkpoint

• How to Cluster Sessions into Intent Threads

  • Detecting ambient domains

  • Extending the database for intent threads

  • Clustering sessions into threads

  • Scoring and classifying threads

  • Putting it together

  • Checkpoint

• How to Clean Up Self-Referential Noise

  • The two problems

  • One definition, applied everywhere

  • Defending the enrichment boundary too

  • Checkpoint

• How to Label Threads with Claude

  • Storing keys locally

  • The first version, and how it broke

  • Batching the requests

  • Building the prompt and merging results

  • Checkpoint

• How to Ground Labels with context.dev

  • What the API returns

  • Fetching one brand

  • Enriching domains in batches

  • How grounding feeds back into labeling

  • Checkpoint

• How to Design the Dashboard

  • The three-column layout

  • The pipeline state machine

  • Driving the welcome screen from the same machine

  • Wiring the handlers

  • The Resume button

  • Checkpoint

• How to Build the AI Assistant

  • Grounding the conversation

  • Sending a message

  • Model and effort controls

  • Rendering replies and the empty state

  • Checkpoint

• What You've Built, and Where to Take It

  • What the privacy model adds up to

  • Where to take it next

  • Wrapping up

• Resources

  • Source code

  • Core documentation

  • Services used

  • Build tooling

  • Debugging tools

  • Further reading

What You'll Build

On first run, openloops greets you with a centered welcome screen that walks you through the three pipeline steps:

Once you've scanned your history, built sessions, and built the intent map, your browsing reorganizes into status-grouped threads: active, stalled, and dormant. Each one has a confidence score, a plain-language summary, a concrete next step, and a Resume button that reopens the exact pages you left off on. The right column holds a chat assistant grounded in your own threads:

That assistant response reasons across the user's actual threads, ranking them by how easy they are to close against how much of a real decision they still need. It also explains why, which is the most novel part of this build, and depends on the context.dev grounding step you'll add later in this tutorial.

Prerequisites

To follow along, you'll need:

• Node 18+ and a Chromium-based browser (Chrome, Brave, Edge, and so on).

• Comfort with TypeScript and React. You don't need to be an expert, but you should be comfortable reading hooks and async/await.

• Basic familiarity with IndexedDB is helpful but not required, as you'll learn what you need as you go.

Two parts of this build are optional and require your own API key, each with a free tier:

• An Anthropic API key (from platform.claude.com) for AI labeling and the chat assistant

• A context.dev API key (from context.dev) for the brand-grounding step

You can build and use the entire core pipeline, capture, clustering, scoring, without either key, since both are additive layers on top of it.

How openloops Is Structured

Before writing any code, it helps to see the whole shape of the thing. Every stage of openloops reads from one IndexedDB store and writes to the next:

chrome.history (backfill) ──┐
chrome.tabs.onUpdated (live)─┴─→ raw_events
                                     │  noise filter
                                     ▼
                                  sessions
                                     │  ambient detection + clustering + scoring
                                     ▼
                               intent_threads
                                     │
                                     ▼
                              React dashboard
                                     │  optional, opt-in
                                     ├──→ brand enrichment   (context.dev)
                                     └──→ AI labeling + next step (Claude)
                                              │
                                              ▼  optional, opt-in
                                        AI assistant chat (Claude)

Each stage is a separate module under src/pipeline/, and each one is independently inspectable: you can open Chrome DevTools, look at raw_events, sessions, or intent_threads directly in the Application tab, and rebuild any single stage without touching the others.

The Shared Types

Every stage consumes and produces the same handful of TypeScript interfaces, defined once in src/types.ts:

// Shared TypeScript interfaces for the openloops pipeline.
// Each stage of the pipeline consumes and produces these types.

export interface RawEvent {
  id: string;
  url: string;
  domain: string;
  title: string;
  visitedAt: number;         // epoch ms
  source: "backfill" | "live";
}

export interface Session {
  id: string;
  events: RawEvent[];
  startedAt: number;
  endedAt: number;
  domains: string[];
  keywords: string[];
}

export interface IntentThread {
  id: string;
  title: string;
  summary?: string;
  nextStep?: string;   // one concrete action to move the thread forward
  sessions: Session[];
  type: "buying" | "research" | "planning" | "learning" | "unclassified";
  confidence: number;        // 0-1
  status: "active" | "stalled" | "dormant";
  firstSeen: number;
  lastSeen: number;
  distinctDays: number;
  signals: string[];
}

export interface Brand {
  domain: string;
  name: string;
  description: string;
  industry: string;
  logoUrl: string;
  brandColor: string;
}

Most fields on IntentThread, confidence, status, signals, and distinctDays get filled in by pure local heuristics later in this guide, when you cluster and score threads. summary and nextStep stay undefined until the optional AI labeling step, covered after that, fills them in.

This is the pattern that makes the whole project work: the core data model functions on its own, and AI makes it richer.

The Manifest

openloops is a Manifest V3 extension with three permissions and three host permissions:

{
  "manifest_version": 3,
  "name": "openloops",
  "version": "0.0.1",
  "description": "Reconstruct your browsing history into an AI-labeled map of intent threads: active decisions, stalled research, open questions. Fully local.",

  "permissions": ["history", "tabs", "storage"],
  "host_permissions": [
    "https://api.anthropic.com/*",
    "https://api.context.dev/*",
    "https://logos.context.dev/*"
  ],

  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  },

  "options_page": "src/dashboard/index.html",

  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "action": {
    "default_title": "openloops",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  }
}

The permissions, host permissions, and options_page entry each carry specific weight:

• permissions: ["history", "tabs", "storage"] are the only permissions the core pipeline needs. history reads your browsing history for the backfill, tabs lets the service worker observe new page loads and lets "Resume" reopen tabs, and storage is where API keys and preferences live.

• host_permissions are separate, and only matter if you use the optional AI features. They're what let the dashboard make fetch() calls to Anthropic and context.dev without hitting CORS errors.

• options_page points at the dashboard. Setting it this way, instead of a default_popup, means clicking the toolbar icon opens the dashboard as a full browser tab rather than a tiny popup, which matters once you're looking at a multi-column layout with status-grouped cards and a chat panel.

How to Scaffold the Extension

Start with Vite and the CRXJS plugin, which compiles a Manifest V3 extension with hot module reloading:

npm create vite@latest openloops -- --template react-ts
cd openloops
npm install @crxjs/vite-plugin idb react-markdown

Your vite.config.ts wires CRXJS to your manifest.json, and from there, Vite handles compiling src/background.ts to a real .js file that Chrome can load (a raw .ts service worker path in the manifest will fail with a registration error, which we'll debug in the next section).

The dashboard's entry point is a standard React 18 root:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>openloops</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./main.tsx"></script>
  </body>
</html>

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./app.css";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Build it, then load it as an unpacked extension:

npm run build

In Chrome, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the dist/ folder. With nothing else built yet, clicking the toolbar icon should open a blank dashboard tab, and the service worker (visible from the extension card's "service worker" link) should log [openloops] Extension installed. on install.

With that foundation in place, it's time to start filling raw_events with your actual browsing history.

How to Capture Your Browsing History

Every record in openloops starts life as a RawEvent, the type you saw earlier: a URL, a domain, a title, a timestamp, and a source of either "backfill" or "live".

Two pipelines populate it:

• A one-time backfill that reads your last 14 days of chrome.history on demand

• Live capture, which listens for new page loads from this point forward

Both paths share a handful of small helpers and write through the same IndexedDB layer, so it's worth building those first.

A Few Shared Helpers

Create src/lib/util.ts:

export function isHttpUrl(url: string): boolean {
  return url.startsWith("http://") || url.startsWith("https://");
}

export function extractDomain(url: string): string {
  try {
    const { hostname } = new URL(url);
    return hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function isLocalHost(domain: string): boolean {
  if (domain === "localhost" || domain === "127.0.0.1") return true;
  if (domain.endsWith(".local")) return true;

  const octets = domain.split(".");
  if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o))) {
    const [a, b] = octets.map(Number);
    if (a === 10) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 192 && b === 168) return true;
  }

  return false;
}

export function hashId(url: string, visitedAt: number): string {
  const str = `\({url}|\){visitedAt}`;
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
    hash |= 0;
  }
  return (hash >>> 0).toString(36);
}

Each of these four functions solves a problem you won't notice until later in the build:

• isHttpUrl is the shared scheme guard used by both live capture and the backfill, and the single gate that keeps chrome://, chrome-extension://, about:, and file:// URLs out of your data entirely. Both capture paths call it before anything else.

• extractDomain strips a leading www. and returns the hostname, which is a simplification: bbc.co.uk and news.bbc.co.uk wouldn't collapse to the same domain under this logic, since true registrable-domain extraction needs the Public Suffix List. If the URL is malformed, it just returns the input unchanged rather than throwing.

• isLocalHost exists for one reason: when you add brand enrichment later in this guide, you'll be sending domain names to an external API. localhost:5173 or 192.168.1.50 are meaningless to that API and would just be wasted lookups, so it's better to filter them here, once, at the source. It checks for localhost, 127.0.0.1, .local hostnames, and the standard private IPv4 ranges (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x).

• hashId combines the URL and timestamp into a short, deterministic string using a simple hashing algorithm (djb2), so the same (url, visitedAt) pair always produces the same ID. This makes writes idempotent: re-running the backfill produces the same IDs for the same visits, so IndexedDB's put overwrites cleanly instead of duplicating, which is what makes "Scan my history" safe to click more than once.

The Database Layer (So Far)

openloops stores everything in IndexedDB via the idb wrapper, which gives you a typed, promise-based API over the raw IndexedDB calls. Create src/db/index.ts:

import { openDB, type DBSchema, type IDBPDatabase } from "idb";
import type { RawEvent } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
}

const DB_NAME = "openloops";
const DB_VERSION = 1;

let _db: Promise<IDBPDatabase<OpenloopsDB>> | null = null;

export function getDB(): Promise<IDBPDatabase<OpenloopsDB>> {
  if (!_db) {
    _db = openDB<OpenloopsDB>(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
      },
    });
  }
  return _db;
}

export async function clearEvents(): Promise<void> {
  const db = await getDB();
  return db.clear("raw_events");
}

export async function putEvents(events: RawEvent[]): Promise<void> {
  if (events.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("raw_events", "readwrite");
  await Promise.all([...events.map((e) => tx.store.put(e)), tx.done]);
}

export async function getAllEvents(): Promise<RawEvent[]> {
  const db = await getDB();
  return db.getAllFromIndex("raw_events", "by_visitedAt");
}

export async function getEventCount(): Promise<number> {
  const db = await getDB();
  return db.count("raw_events");
}

Four small functions round out this first version of the database layer: clearEvents wipes the store, which the backfill calls first so every scan starts from a clean snapshot. putEvents writes a batch using IDB's put, which overwrites rather than duplicates. getAllEvents returns everything sorted by visitedAt via the index. And getEventCount returns a simple count for the dashboard.

_db is a module-level singleton promise, so every part of the extension, the service worker and the dashboard alike, shares one connection. DB_VERSION starts at 1 here. As you add sessions, intent threads, and brand data in later parts, you'll add new stores guarded by if (!db.objectStoreNames.contains(...)) and bump this number. That guard means existing users upgrade safely without touching stores that already exist.

Capturing New Visits Live

The service worker is the always-on part of the extension. Create src/background.ts:

import { hashId, extractDomain, isHttpUrl } from "./lib/util";
import { putEvents } from "./db/index";
import type { RawEvent } from "./types";

chrome.runtime.onInstalled.addListener(() => {
  console.log("[openloops] Extension installed.");
});

chrome.action.onClicked.addListener(() => {
  chrome.runtime.openOptionsPage();
});

const DEDUP_MS = 3_000;
const recentCaptures = new Map<number, { url: string; at: number }>();

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const url = tab.url;

  if (!isHttpUrl(url)) return;

  const last = recentCaptures.get(tabId);
  const now = Date.now();
  if (last && last.url === url && now - last.at < DEDUP_MS) {
    console.log(`[openloops] dedup skip — tab \({tabId} \){url}`);
    return;
  }

  recentCaptures.set(tabId, { url, at: now });

  const event: RawEvent = {
    id: hashId(url, now),
    url,
    domain: extractDomain(url),
    title: tab.title ?? url,
    visitedAt: now,
    source: "live",
  };

  putEvents([event]).then(() => {
    console.log(`[openloops] captured \({event.domain} — \){event.title}`);
  }).catch((err) => {
    console.error("[openloops] putEvents failed:", err);
  });
});

chrome.action.onClicked is what makes the toolbar icon open the dashboard as a tab rather than a popup, working together with the options_page entry in your manifest.

Live capture happens inside the tabs.onUpdated listener, which Chrome fires repeatedly as a page loads, redirects, and updates its title, though you should only care about the moment changeInfo.status === "complete". From there, isHttpUrl drops anything that isn't a real web page, the dedup guard collapses the duplicate "complete" events that SPAs love to fire, and the rest becomes a RawEvent with source: "live".

That dedup guard is best-effort by design: recentCaptures is a plain in-memory Map, and Chrome can suspend the service worker between events, which wipes the Map along with it. It still collapses duplicate bursts within a single waking session, just not across service worker restarts, and that's an acceptable tradeoff since hashId already makes any duplicate that slips through harmless once it reaches IndexedDB.

The final write also looks slightly unusual: putEvents([event]).then(...).catch(...) instead of await. The listener doesn't need to block on the write finishing, and the service worker stays alive long enough to complete a single IndexedDB write even if it's about to be suspended, so firing the write and moving on is enough.

That source field carries more weight than it first appears, since it's how later code distinguishes "the user actually scanned their history" from "the extension has only been open for five minutes". This matters for onboarding when you design the dashboard later in this guide.

Build and reload the extension now (npm run build, then click the reload icon on the extension card in chrome://extensions), browse a few pages, then open the service worker's DevTools by clicking "service worker" on the extension card. You'll be able to see [openloops] captured ... log lines appear as confirmation that live capture is working.

Backfilling 14 Days of History

Live capture only sees what happens after you install the extension, so to make openloops useful immediately, you also need to backfill recent history. Create src/pipeline/backfill.ts:

import { extractDomain, hashId, isHttpUrl } from "../lib/util";
import { putEvents, clearEvents } from "../db/index";
import type { RawEvent } from "../types";

const CONCURRENCY = 50;

async function visitsForItem(
  item: chrome.history.HistoryItem,
  startTime: number
): Promise<RawEvent[]> {
  if (!item.url) return [];
  if (!isHttpUrl(item.url)) return [];

  const visits = await chrome.history.getVisits({ url: item.url });

  const events: RawEvent[] = [];
  for (const visit of visits) {
    if (!visit.visitTime || visit.visitTime < startTime) continue;

    events.push({
      id: hashId(item.url, visit.visitTime),
      url: item.url,
      domain: extractDomain(item.url),
      title: item.title ?? item.url,
      visitedAt: visit.visitTime,
      source: "backfill",
    });
  }

  return events;
}

export async function backfillHistory(days = 14): Promise<number> {
  await clearEvents();

  const startTime = Date.now() - days * 24 * 60 * 60 * 1000;

  const historyItems = await chrome.history.search({
    text: "",
    startTime,
    maxResults: 100_000,
  });

  let totalWritten = 0;

  for (let i = 0; i < historyItems.length; i += CONCURRENCY) {
    const batch = historyItems.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.all(
      batch.map((item) => visitsForItem(item, startTime))
    );
    const events = batchResults.flat();
    await putEvents(events);
    totalWritten += events.length;
  }

  return totalWritten;
}

backfillHistory starts by calling clearEvents and wiping the store so each run produces a clean snapshot for the chosen window. Every real visit still exists in chrome.history, so nothing is lost by starting over. It then searches with maxResults: 100_000, since the default of 100 is far too low for anyone with more than a few days of real browsing.

Each matching HistoryItem goes through visitsForItem, which skips items that Chrome returns with no url at all, a quirk of some deleted-history entries, and skips non-web URLs using isHttpUrl, before fetching that item's full visit list.

Calling getVisits here, instead of relying on search alone, matters because chrome.history.search is tempting as a single call, but it collapses every visit to a URL down to just the most recent one. If you visited the same Stack Overflow answer three times over two days while debugging something, search gives you one row, and in the next section, where you segment events into sessions, you need all three: that's the difference between "one visit, three days ago" and "a sustained debugging session."

getVisits gives you that full timestamp list, but it returns all history for a URL regardless of date range, so visitsForItem filters by startTime itself. And because chrome.history.search can return tens of thousands of items for a heavy browser history, the backfill fans out to getVisits in batches of CONCURRENCY, set to 50, rather than firing everything at once. Chrome doesn't document a hard limit on concurrent getVisits calls, but 50 in flight at a time keeps things responsive without flooding it.

Checkpoint

You can verify live capture by browsing normally and watching raw_events fill up: open chrome://extensions, click "service worker" on the openloops card, then go to the Application tab → IndexedDB → openloops → raw_events, where each row should be a RawEvent with source: "live".

backfillHistory itself doesn't have a UI yet, but you'll wire it up to a "Scan my history" button when you build the dashboard rail in Part 13. For now, it's enough that it compiles and that raw_events is filling up from live capture. In the next part you'll start turning that raw stream into something structured: sessions.

How to Turn Noise into Sessions

A real browsing history is full of activity that has nothing to do with what you were actually trying to do. An afternoon of research might be interleaved with dozens of visits to Gmail, Slack, or YouTube, along with pages whose titles are just "New Tab" or "Dashboard" because the page hadn't finished loading when the browser recorded it.

Before any of this can be grouped into something meaningful, two things need to happen: the noise needs to be filtered out, and what remains needs to be broken into sessions, contiguous stretches of activity separated by gaps in time.

This section builds both of those steps, along with a small keyword extractor that each session uses to describe what it was about, since that description is what later powers clustering.

Filtering Out Noise

Create src/pipeline/noise.ts:

import type { RawEvent } from "../types";
import { isHttpUrl, isLocalHost } from "../lib/util";

export const BLOCKED_DOMAINS: readonly string[] = [
  "mail.google.com",
  "outlook.live.com",
  "outlook.office.com",
  "calendar.google.com",
  "slack.com",
  "app.slack.com",
  "discord.com",
  "web.whatsapp.com",
  "teams.microsoft.com",
  "messenger.com",
];

export const ADULT_DOMAINS: readonly string[] = [
  "xvideos.com",
  "pornhub.com",
  "xnxx.com",
  "xhamster.com",
  "redtube.com",
  "youporn.com",
  "spankbang.com",
];

export const JUNK_DOMAINS: readonly string[] = [
  "trk.myperfect2give.com",
  "t.buenotraffic.com",
  "bwredir.com",
  "osom.saintscommunity.net",
];

const ALL_BLOCKED = [...BLOCKED_DOMAINS, ...ADULT_DOMAINS, ...JUNK_DOMAINS];

function domainIsBlocked(domain: string): boolean {
  return ALL_BLOCKED.some(
    (blocked) => domain === blocked || domain.endsWith("." + blocked)
  );
}

export const NOISE_TITLE_PREFIXES: readonly string[] = [
  "new tab",
  "new chat",
  "untitled",
  "inbox",
  "home",
  "dashboard",
  "sign in",
  "log in",
  "loading",
];

function titleIsGeneric(title: string, domain: string): boolean {
  if (title.trim() === "") return true;
  if (title.toLowerCase() === domain.toLowerCase()) return true;

  const lower = title.toLowerCase();
  return NOISE_TITLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
}

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

isNoise is the single function the rest of the pipeline calls, and it layers four checks on top of each other, each one catching a different kind of noise.

The first two checks reuse the helpers from earlier: isHttpUrl and isLocalHost drop anything that isn't a real web page or that points at a local development server, the same filters that already protect capture. Checking them again here is a deliberate belt-and-suspenders measure: if anything ever reaches raw_events without having passed through capture's checks, it still can't make it into a session.

BLOCKED_DOMAINS covers communication and productivity tools, Gmail, Slack, Discord, WhatsApp Web, and similar. Those tools that you visit constantly but that carry no research intent of their own. domainIsBlocked matches both the exact domain and any subdomain, so slack.com in the list also catches app.slack.com. ADULT_DOMAINS and JUNK_DOMAINS exist for related reasons, keeping adult content and known tracker or redirect domains out of your threads entirely.

BLOCKED_DOMAINS is a curated, static list, and later in this guide it's complemented by a second, frequency-based detector in ambient.ts. This drops any domain that shows up in nearly every session regardless of what that domain actually is.

The last check, titleIsGeneric, catches pages whose titles tell you nothing useful: an empty title, a title that's identical to the domain name, or a title that starts with a generic prefix like "New Tab", "Dashboard", "Loading...", or "Sign in". NOISE_TITLE_PREFIXES is matched against the start of the lowercased title, so "Dashboard | Vercel" gets dropped right alongside a bare "Dashboard", while a content-rich title on that same domain passes through untouched.

Extracting Keywords

Create src/pipeline/keywords.ts. This isn't NLP, just frequency counting after stopword removal. This is good enough to surface something like "typescript generics" or "react hooks" from a session of related browsing:

import { BLOCKED_DOMAINS } from "./noise";

export const STOPWORDS: ReadonlySet<string> = new Set([
  "the", "and", "for", "with", "you", "your", "how", "what", "this", "that",
  "from", "are", "was", "not", "but", "all", "can", "has", "have", "will",
  "its", "out", "one", "get", "our", "had", "just", "about", "also", "more",
  "into", "than", "then", "when", "their", "there", "which", "would", "been",
  "his", "her", "who", "they", "she", "him", "now", "any", "way", "use",
  "using", "used", "make", "made",
  "google", "youtube", "search", "chat", "new", "home", "www", "com", "org",
  "net", "page", "site", "tab", "view", "app", "log", "sign", "login",
  "official", "free", "online", "best", "top", "open",
]);

export const PLATFORM_STOPWORDS: ReadonlySet<string> = new Set([
  "instagram", "facebook", "youtube", "claude", "google", "linkedin",
  "twitter", "reddit", "netflix", "amazon", "gmail", "whatsapp", "tiktok",
  "messenger",
  "stories", "story", "reel", "reels", "shorts", "short", "feed", "watch",
  "video", "videos", "music", "post", "posts", "message", "messages",
  "dm", "dms", "notification", "notifications", "profile", "home", "login",
  "signin", "follow", "followers",
]);

function derivedDomainLabels(): Set<string> {
  const labels = new Set<string>();
  for (const domain of BLOCKED_DOMAINS) {
    const label = domain.split(".").at(-2);
    if (label) labels.add(label);
  }
  return labels;
}

const ALL_STOP_TOKENS: ReadonlySet<string> = new Set([
  ...STOPWORDS,
  ...PLATFORM_STOPWORDS,
  ...derivedDomainLabels(),
]);

export function extractKeywords(titles: string[], max = 8): string[] {
  const freq = new Map<string, number>();

  for (const title of titles) {
    const tokens = title.toLowerCase().split(/[^a-z0-9]+/);
    for (const token of tokens) {
      if (token.length < 3) continue;
      if (/^\d+$/.test(token)) continue;
      if (ALL_STOP_TOKENS.has(token)) continue;

      freq.set(token, (freq.get(token) ?? 0) + 1);
    }
  }

  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, max)
    .map(([token]) => token);
}

extractKeywords takes the page titles from a group of events and returns the handful of words that show up most often, after stripping out everything that isn't a topic. That stripping is doing more work than the name "stopwords" suggests.

STOPWORDS covers common English function words like "the" and "with", plus generic site chrome like "search", "login", and "page". On its own, this would still let through tokens like "instagram" or "reels" from a title such as "Reels · Instagram", and those tokens would then show up as keywords for that session.

That gap is what PLATFORM_STOPWORDS closes. A title like "Reels · Instagram" or "Watch - YouTube" identifies the tool you were using, not what you were doing with it. So PLATFORM_STOPWORDS strips out platform and brand names along with social media UI chrome like "stories", "feed", "dm", and "notifications". Without this list, sessions on social platforms would extract keywords like "instagram" or "watch". Those would become thread titles that quietly pull unrelated sessions together during clustering, since every social-media session would share that one meaningless keyword.

derivedDomainLabels keeps a third source of stopwords in sync automatically: for every domain in BLOCKED_DOMAINS, it takes the label immediately before the top-level domain. So mail.google.com becomes google and web.whatsapp.com becomes whatsapp. Adding a new domain to that blocklist later also prevents its name from polluting keywords, without any extra bookkeeping.

With all three sets merged once at module load into ALL_STOP_TOKENS, extractKeywords itself is straightforward: lowercase every title, split on anything that isn't a letter or digit, drop tokens shorter than three characters or made entirely of digits, and drop anything in ALL_STOP_TOKENS. Then count what's left and return the most frequent entries.

Extending the Database For Sessions

Sessions need a place to live. Earlier in this guide, src/db/index.ts defined a schema with just raw_events at version 1. We'll add a sessions store and bump the version to 2.

First, extend the schema and the upgrade callback:

import type { RawEvent, Session } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
}

const DB_VERSION = 2;

export function getDB(): Promise<IDBPDatabase<OpenloopsDB>> {
  if (!_db) {
    _db = openDB<OpenloopsDB>(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
      },
    });
  }
  return _db;
}

Then add the helper functions sessions need, alongside the raw_events helpers you already wrote. They follow the same shape: putSessions writes a batch idempotently, clearSessions wipes the store before a rebuild, getAllSessions returns everything sorted by startedAt via the index, and getSessionCount returns a total.

export async function putSessions(sessions: Session[]): Promise<void> {
  if (sessions.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("sessions", "readwrite");
  await Promise.all([...sessions.map((s) => tx.store.put(s)), tx.done]);
}

export async function clearSessions(): Promise<void> {
  const db = await getDB();
  return db.clear("sessions");
}

export async function getAllSessions(): Promise<Session[]> {
  const db = await getDB();
  return db.getAllFromIndex("sessions", "by_startedAt");
}

export async function getSessionCount(): Promise<number> {
  const db = await getDB();
  return db.count("sessions");
}

The if (!db.objectStoreNames.contains(...)) guard from earlier is what makes this safe: anyone who already has a version-1 database, with raw_events full of real data, gets the new sessions store added on top, without touching what's already there.

Segmenting Events into Sessions

A session is a contiguous block of browsing activity, with a new one starting whenever the gap between two consecutive events exceeds SESSION_GAP_MS. Create src/pipeline/sessions.ts:

import { getAllEvents, clearSessions, putSessions } from "../db/index";
import { isNoise } from "./noise";
import { extractKeywords } from "./keywords";
import { hashId } from "../lib/util";
import type { RawEvent, Session } from "../types";

const SESSION_GAP_MS = 30 * 60 * 1000;

function rankDomains(events: RawEvent[]): string[] {
  const freq = new Map<string, number>();
  for (const e of events) {
    freq.set(e.domain, (freq.get(e.domain) ?? 0) + 1);
  }
  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([domain]) => domain);
}

function buildSession(events: RawEvent[]): Session {
  const startedAt = events[0].visitedAt;
  const endedAt = events[events.length - 1].visitedAt;

  return {
    id: hashId(events[0].url, startedAt),
    events,
    startedAt,
    endedAt,
    domains: rankDomains(events),
    keywords: extractKeywords(events.map((e) => e.title)),
  };
}

export async function buildSessions(): Promise<{ events: number; sessions: number }> {
  const allEvents = await getAllEvents();

  const meaningful = allEvents.filter((e) => !isNoise(e));

  if (meaningful.length === 0) {
    await clearSessions();
    return { events: 0, sessions: 0 };
  }

  const sessions: Session[] = [];
  let currentGroup: RawEvent[] = [meaningful[0]];

  for (let i = 1; i < meaningful.length; i++) {
    const gap = meaningful[i].visitedAt - meaningful[i - 1].visitedAt;

    if (gap > SESSION_GAP_MS) {
      sessions.push(buildSession(currentGroup));
      currentGroup = [meaningful[i]];
    } else {
      currentGroup.push(meaningful[i]);
    }
  }
  sessions.push(buildSession(currentGroup));

  const substantive = sessions.filter(
    (s) => !(s.events.length === 1 && s.keywords.length === 0)
  );

  await clearSessions();
  await putSessions(substantive);

  return { events: meaningful.length, sessions: substantive.length };
}

buildSessions does five things in order:

1. loads every raw event sorted by time,

2. drops anything isNoise flags,

3. walks the remaining list and starts a new session whenever the gap between two consecutive events exceeds SESSION_GAP_MS (pushing the final in-progress group once the loop ends since nothing else closes it off),

4. drops sessions that turned out to be a single event with no extractable keywords (usually stray page loads that never connected to anything else),

5. and persists the result.

Each session's domains and keywords come from rankDomains and extractKeywords running over just the events in that group. rankDomains counts how many events came from each domain and orders them by frequency, so the most-visited domain in a session comes first.

A worked example makes "walking the list" concrete. Take five events that survive noise filtering, A through E:

A  t= 0 min  "TypeScript generics - Stack Overflow"   stackoverflow.com
B  t= 5 min  "TypeScript Handbook"                    typescriptlang.org
C  t=10 min  "microsoft/TypeScript - GitHub"          github.com
   ↑ gap to D = 45 min  >  SESSION_GAP_MS (30 min)  → SPLIT HERE
D  t=55 min  "React hooks explained - YouTube"         youtube.com
E  t=60 min  "useEffect cleanup - Stack Overflow"     stackoverflow.com

As the loop walks from A to B to C, each gap is under the 30-minute limit, so all three stay in the same group. The jump from C to D is 45 minutes, which crosses SESSION_GAP_MS, so the loop closes off [A, B, C] as Session 1 and starts a fresh group with D. From D to E is only 5 minutes, so E joins D, and that group becomes Session 2 once the loop ends.

Session 1 ends up tagged with keywords like typescript and generics, while Session 2 is tagged with react and hooks, even though both sessions happened on the same day.

SESSION_GAP_MS is set to 30 minutes because that's the same default that Google Analytics and similar tools use, and it works well for most browsing patterns.

The tradeoff runs in both directions: a shorter gap produces more, smaller sessions, which gives clustering a more granular signal but risks fragmenting one continuous task into several pieces. A longer gap produces fewer, larger sessions, which risks merging activity that was actually unrelated.

30 minutes is a reasonable starting point, and it's the kind of constant you can come back and tune once you see how your own threads turn out.

Checkpoint

buildSessions doesn't have a UI yet either. It'll get wired up to a "Build sessions" button alongside "Scan my history" when you design the dashboard later in this guide.

For now, the goal is just for everything in this section to compile cleanly: src/pipeline/noise.ts, src/pipeline/keywords.ts, the updated src/db/index.ts, and src/pipeline/sessions.ts should all build without errors. getDB() should report version 2 the next time the extension reloads (visible in DevTools under Application → IndexedDB → openloops, where the database now lists both raw_events and sessions as object stores).

With sessions in place, the next section takes this structured-but-unconnected data and groups sessions together into the intent threads this whole project is named after.

How to Cluster Sessions into Intent Threads

Sessions group events that happened close together in time. But the things you're actually trying to do rarely fit inside one session. Comparing laptops might span three sessions over four days. A question you keep meaning to look into might surface for ten minutes every few days for two weeks.

This section groups related sessions together into intent threads, then scores each thread for how confident openloops is that it represents something real and how alive it still is.

Two files do this work. src/pipeline/ambient.ts detects domains that are part of your daily routine rather than any particular intent, so they don't create false similarity between unrelated sessions. src/pipeline/threads.ts does the actual clustering and scoring.

Detecting Ambient Domains

Some domains show up in almost every session regardless of what you're doing: youtube.com as background noise, github.com if you're a developer who commits daily, or claude.ai if you use it as a general assistant. If clustering compared sessions on these domains the same way it compares them on anything else, two completely unrelated sessions would look similar just because they both touched youtube.com, and everything would eventually merge into one enormous thread.

ambient.ts solves this with a frequency check: a domain is ambient if it shows up on a large enough fraction of your active days, regardless of topic.

Create src/pipeline/ambient.ts:

import type { Session } from "../types";

export const UBIQUITY_THRESHOLD = 0.6;
export const MIN_ACTIVE_DAYS = 3;

function toDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

export function detectAmbientDomains(sessions: Session[]): Set<string> {
  const allEvents = sessions.flatMap((s) => s.events);

  const activeDays = new Set(allEvents.map((e) => toDay(e.visitedAt)));
  const totalActiveDays = activeDays.size;

  if (totalActiveDays < MIN_ACTIVE_DAYS) {
    return new Set();
  }

  const domainDayMap = new Map<string, Set<string>>();
  for (const event of allEvents) {
    const day = toDay(event.visitedAt);
    if (!domainDayMap.has(event.domain)) {
      domainDayMap.set(event.domain, new Set());
    }
    domainDayMap.get(event.domain)!.add(day);
  }

  const ambient = new Set<string>();
  for (const [domain, days] of domainDayMap) {
    const ubiquity = days.size / totalActiveDays;
    if (ubiquity >= UBIQUITY_THRESHOLD) {
      ambient.add(domain);
      console.log(
        `[openloops] ambient: \({domain} (\){days.size}/\({totalActiveDays} days, ubiquity=\){ubiquity.toFixed(2)})`
      );
    }
  }

  return ambient;
}

toDay collapses a timestamp down to a calendar-day string, so two events on the same day produce the same key, regardless of the exact time.

detectAmbientDomains first counts how many distinct days had any browsing activity at all – that's totalActiveDays – then builds a map from each domain to the set of days it appeared on. A domain's ubiquity is days.size / totalActiveDays, the fraction of your active days that domain showed up on. Anything at or above UBIQUITY_THRESHOLD 0.6 gets added to the returned set.

MIN_ACTIVE_DAYS exists because with only one or two days of data, almost every domain you visited would technically appear on 100% of your active days, and the detector would mark everything as ambient. Below three active days, it returns an empty set and skips detection entirely.

This approach has a real tradeoff. It correctly identifies genuinely ambient tools, but it can also suppress a domain you happened to research intensively every single day for a week, which would also cross the 60% threshold.

UBIQUITY_THRESHOLD is the knob for that tradeoff: raising it reduces false positives at the cost of letting some real ambient noise back in.

Extending the Database for Intent Threads

Threads need their own store. Bump DB_VERSION to 3 and add intent_threads, indexed by lastSeen, so the dashboard can show the most recently active threads first:

import type { RawEvent, Session, IntentThread } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
  intent_threads: {
    key: string;
    value: IntentThread;
    indexes: { by_lastSeen: number };
  };
}

const DB_VERSION = 3;

export function getDB(): Promise<IDBPDatabase<OpenloopsDB>> {
  if (!_db) {
    _db = openDB<OpenloopsDB>(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
        if (!db.objectStoreNames.contains("intent_threads")) {
          const s = db.createObjectStore("intent_threads", { keyPath: "id" });
          s.createIndex("by_lastSeen", "lastSeen");
        }
      },
    });
  }
  return _db;
}

Then add the matching helpers:

export async function putThreads(threads: IntentThread[]): Promise<void> {
  if (threads.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("intent_threads", "readwrite");
  await Promise.all([...threads.map((t) => tx.store.put(t)), tx.done]);
}

export async function clearThreads(): Promise<void> {
  const db = await getDB();
  return db.clear("intent_threads");
}

export async function getAllThreads(): Promise<IntentThread[]> {
  const db = await getDB();
  const index = db
    .transaction("intent_threads", "readonly")
    .store.index("by_lastSeen");

  let cursor = await index.openCursor(null, "prev");
  const results: IntentThread[] = [];
  while (cursor) {
    results.push(cursor.value);
    cursor = await cursor.continue();
  }
  return results;
}

export async function getThreadCount(): Promise<number> {
  const db = await getDB();
  return db.count("intent_threads");
}

putThreads, clearThreads, and getThreadCount follow the same pattern as the sessions helpers from earlier. getAllThreads is the odd one out: instead of getAllFromIndex, which only returns ascending order, it opens a cursor on by_lastSeen in "prev" direction and walks it manually. That gives you threads ordered with the most recently active first, the order the dashboard wants for status-grouped cards.

Clustering Sessions into Threads

With ambient domains identified, src/pipeline/threads.ts now does the real work: grouping sessions into threads, then scoring and classifying each one.

The approach is greedy agglomerative clustering. Walk through sessions in chronological order, and for each one, either merge it into the most similar existing thread or start a new thread if nothing is similar enough.

Start with the imports, the tuning constants, and the similarity calculation:

import { getAllSessions, clearThreads, putThreads } from "../db/index";
import { detectAmbientDomains } from "./ambient";
import { hashId } from "../lib/util";
import type { Session, IntentThread } from "../types";

export const SIMILARITY_THRESHOLD = 0.15;
export const DOMAIN_WEIGHT = 0.5;
export const KEYWORD_WEIGHT = 0.5;

interface ThreadBuilder {
  id: string;
  sessions: Session[];
  domainSet: Set<string>;
  keywordSet: Set<string>;
}

function jaccard(a: Set<string>, b: Set<string>): number {
  if (a.size === 0 && b.size === 0) return 0;
  let intersection = 0;
  for (const item of a) {
    if (b.has(item)) intersection++;
  }
  const union = a.size + b.size - intersection;
  return intersection / union;
}

function similarity(
  session: Session,
  thread: ThreadBuilder,
  ambient: Set<string>
): number {
  const sessionDomains  = new Set(session.domains.filter((d) => !ambient.has(d)));
  const threadDomains   = new Set([...thread.domainSet].filter((d) => !ambient.has(d)));
  const sessionKeywords = new Set(session.keywords);

  const domainScore   = jaccard(sessionDomains, threadDomains);
  const keywordScore  = jaccard(sessionKeywords, thread.keywordSet);

  return DOMAIN_WEIGHT * domainScore + KEYWORD_WEIGHT * keywordScore;
}

ThreadBuilder is a mutable accumulator used only during clustering: a thread in progress, with its sessions plus the union of all domains and keywords seen so far. jaccard is the standard set-similarity measure, the size of the intersection divided by the size of the union, returning 0 for two empty sets rather than dividing zero by zero.

similarity compares one candidate session against one in-progress thread. Before comparing domains, it filters ambient domains out of both sides, so a shared youtube.com never contributes to the score. It then computes a domain Jaccard score and a keyword Jaccard score separately, and combines them with DOMAIN_WEIGHT and KEYWORD_WEIGHT, both 0.5, giving domain overlap and keyword overlap equal say in the final number.

Next, the clustering loop itself:

function clusterSessions(
  sessions: Session[],
  ambient: Set<string>
): ThreadBuilder[] {
  const threads: ThreadBuilder[] = [];

  for (const session of sessions) {
    let bestThread: ThreadBuilder | null = null;
    let bestScore = 0;

    for (const thread of threads) {
      const score = similarity(session, thread, ambient);
      if (score > bestScore) {
        bestScore = score;
        bestThread = thread;
      }
    }

    if (bestThread && bestScore >= SIMILARITY_THRESHOLD) {
      bestThread.sessions.push(session);
      for (const d of session.domains)  bestThread.domainSet.add(d);
      for (const k of session.keywords) bestThread.keywordSet.add(k);
    } else {
      threads.push({
        id: hashId(session.id, session.startedAt),
        sessions: [session],
        domainSet:  new Set(session.domains),
        keywordSet: new Set(session.keywords),
      });
    }
  }

  return threads;
}

clusterSessions relies on sessions already being sorted chronologically, which getAllSessions guarantees via its index. For each session, it scores against every thread built so far and keeps the best match.

If that best score clears SIMILARITY_THRESHOLD, the session merges in and its domains and keywords get folded into the thread's accumulated sets. This means that later sessions are compared against the thread's entire accumulated history rather than only its seed session. If nothing clears the threshold, the session becomes the seed of a brand-new thread.

A worked example shows how this plays out. Suppose detectAmbientDomains returned { youtube.com }, and three sessions arrive in this order:

S1: domains=[stackoverflow.com, typescriptlang.org]
    keywords=[typescript, generics, interface, mapped]

S2: domains=[stackoverflow.com, typescriptlang.org, github.com]
    keywords=[typescript, generics, utility, types]

S3: domains=[python.org, docs.python.org]
    keywords=[python, async, await, coroutine]

S1 arrives first. With no threads yet, it seeds Thread A: domainSet = {stackoverflow.com, typescriptlang.org}, keywordSet = {typescript, generics, interface, mapped}.

S2 is scored against Thread A. Neither set contains the ambient youtube.com, so nothing gets filtered out. The domain Jaccard is |{stackoverflow.com, typescriptlang.org}| / |{stackoverflow.com, typescriptlang.org, github.com}|, or 2/3 ≈ 0.667. The keyword Jaccard is |{typescript, generics}| / |{typescript, generics, interface, mapped, utility, types}|, or 2/6 ≈ 0.333. The combined similarity is 0.5 × 0.667 + 0.5 × 0.333 = 0.5, comfortably above SIMILARITY_THRESHOLD (0.15), so S2 merges into Thread A, whose sets grow to include github.com, utility, and types.

S3 is scored against Thread A. There's no overlap at all between {python.org, docs.python.org} and Thread A's domains, or between their keyword sets, so both Jaccard scores are 0 and the combined similarity is 0. That's below the threshold, so S3 seeds a new Thread B.

The result: Thread A holds the TypeScript research across two sessions, and Thread B holds the Python session on its own.

SIMILARITY_THRESHOLD is the single most consequential constant in this file, and 0.15 is lower than you might guess for a 50/50 weighted Jaccard score. A starting value like 0.3 sounds more principled. That would mean two sessions need to share roughly a third of their combined domains and keywords before they're considered part of the same thread.

Run that against real, messy browsing history, though, and it produces far too many threads: sessions that were obviously part of the same research, but didn't share quite enough keywords to clear 0.3, end up scattered across separate threads.

Dropping the threshold to 0.15 lets sessions merge on weaker but still real signal. Two sessions sharing just one domain and one keyword out of several can already cross 0.15, and the result is fewer, more coherent threads that actually match what the browsing history looks like.

This is the kind of constant you tune empirically rather than deriving it from first principles: build your threads, look at the result, and adjust.

buildThreads, covered next, prints a table of every thread's title, type, status, confidence, and top keywords specifically so you can eyeball this. If two threads obviously belong together, lower SIMILARITY_THRESHOLD. If one thread is clearly several unrelated topics glued together, raise it.

Scoring and Classifying Threads

Clustering produces groups of sessions, but a group of sessions isn't yet an IntentThread. The rest of threads.ts turns each group into something with a type, a confidence score, a status, and a set of human-readable signals explaining why.

A few small helpers come first:

export const BUYING_WORDS: readonly string[] = [
  "vs", "versus", "alternative", "alternatives",
  "comparison", "pricing", "price", "review", "reviews", "best",
];

export const LEARNING_WORDS: readonly string[] = [
  "how to", "tutorial", "tutorials", "docs", "documentation",
  "guide", "learn", "example", "examples", "crash course", "introduction",
];

const STATUS_ACTIVE_MS  = 48 * 60 * 60 * 1000;
const STATUS_STALLED_MS = 7  * 24 * 60 * 60 * 1000;

function toTitleCase(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

function findMatches(titles: string[], wordList: readonly string[]): string[] {
  const lower = titles.map((t) => t.toLowerCase());
  const found = new Set<string>();

  for (const word of wordList) {
    const isPhrase = word.includes(" ");
    for (const title of lower) {
      if (isPhrase) {
        if (title.includes(word)) found.add(word);
      } else {
        const tokens = title.split(/[^a-z0-9]+/);
        if (tokens.includes(word)) found.add(word);
      }
    }
  }

  return [...found];
}

function toCalendarDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

BUYING_WORDS and LEARNING_WORDS are small vocabularies that signal intent. findMatches checks a list of page titles against one of these vocabularies, and handles single words and phrases differently: a multi-word entry like "how to" is checked as a substring, since it's specific enough that false positives are unlikely. But a single word like "review" is checked as a whole token, split out of the title on non-alphanumeric characters.

Without that distinction, "review" would match inside "overview" too, which would misclassify any thread that happened to involve an "Overview" page. toTitleCase and toCalendarDay are small formatting helpers used by the scoring function next.

That scoring function, scoreThread, is the longest function in the project, since it's where every signal collected so far gets turned into the fields on IntentThread:

function scoreThread(builder: ThreadBuilder): IntentThread {
  const { sessions, keywordSet } = builder;

  const firstSeen  = sessions[0].startedAt;
  const lastSeen   = sessions[sessions.length - 1].endedAt;

  const allEvents  = sessions.flatMap((s) => s.events);
  const totalEvents = allEvents.length;
  const daySet     = new Set(allEvents.map((e) => toCalendarDay(e.visitedAt)));
  const distinctDays = daySet.size;

  const allTitles      = allEvents.map((e) => e.title);
  const buyingMatches  = findMatches(allTitles, BUYING_WORDS);
  const learningMatches = findMatches(allTitles, LEARNING_WORDS);

  let type: IntentThread["type"];
  if (buyingMatches.length > 0) {
    type = "buying";
  } else if (learningMatches.length > 0) {
    type = "learning";
  } else if (distinctDays > 5 && sessions.length >= 3) {
    type = "planning";
  } else if (totalEvents >= 3) {
    type = "research";
  } else {
    type = "unclassified";
  }

  const age = Date.now() - lastSeen;
  const status: IntentThread["status"] =
    age < STATUS_ACTIVE_MS  ? "active"  :
    age < STATUS_STALLED_MS ? "stalled" :
    "dormant";

  const confidence = parseFloat((
    Math.min(distinctDays / 5, 1) * 0.35 +
    Math.min(sessions.length / 5, 1) * 0.25 +
    Math.min(totalEvents / 20, 1)  * 0.20 +
    (type !== "unclassified" ? 1 : 0)  * 0.20
  ).toFixed(2));

  const signals: string[] = [];

  if (distinctDays > 1)
    signals.push(`revisited across ${distinctDays} days`);
  if (type === "buying" && buyingMatches.length > 0)
    signals.push(`comparison language: ${buyingMatches.join(", ")}`);
  if (type === "learning" && learningMatches.length > 0)
    signals.push(`learning language: ${learningMatches.join(", ")}`);
  signals.push(`\({sessions.length} session\){sessions.length !== 1 ? "s" : ""}`);
  if (totalEvents > 5)
    signals.push(`${totalEvents} total events`);
  if (type === "planning")
    signals.push("sustained activity across many days");

  const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
  if (ageDays === 0)       signals.push("last active today");
  else if (ageDays === 1)  signals.push("last active yesterday");
  else                     signals.push(`last active ${ageDays} days ago`);

  const title =
    [...keywordSet].slice(0, 3).map(toTitleCase).join(" ") || "Untitled Thread";

  return {
    id: builder.id,
    title,
    sessions,
    type,
    confidence,
    status,
    firstSeen,
    lastSeen,
    distinctDays,
    signals,
  };
}

There's a lot here, so it's worth walking through each field on IntentThread in the order it's computed.

firstSeen and lastSeen come straight from the boundary sessions, since sessions arrives in chronological order from clustering. distinctDays reuses the same calendar-day collapsing as ambient.ts. This time it counts how many different days this thread's events span, regardless of how many total active days you had overall.

Classification into type is a cascade, and the order matters. Comparison language (BUYING_WORDS) is checked first, because a thread where you're comparing two frameworks is "buying" even if it also contains tutorial pages. Comparison intent is the stronger signal.

Learning language comes next. After that, planning is reserved for threads that span more than five distinct days and have at least three sessions of sustained, recurring activity rather than a single deep dive.

research is the catch-all for anything with at least three events that didn't match anything more specific, and unclassified is what's left, usually threads with too little activity to say anything confident about.

status is purely a function of how long ago lastSeen was: under 48 hours is active, under 7 days is stalled, anything older is dormant.

confidence is a weighted sum of four signals, each normalized to a maximum of 1 before weighting, so the total can't exceed 1 either. distinctDays / 5, capped at 1, contributes up to 35%, treating five or more distinct days as fully confident on that axis. sessions.length / 5, capped at 1, contributes up to 25%. totalEvents / 20, capped at 1, contributes up to 20%. And whether type is anything other than unclassified contributes the final 20% as an all-or-nothing bonus.

A thread revisited across five-plus days, across five-plus sessions, with twenty-plus events, that also classified cleanly, scores a full 1.0. A thread that's a single session with two events and no classification scores close to 0.

signals is a plain-English audit trail for the confidence score and status: it explains why a thread looks the way it does, listing things like how many days it was revisited across, what comparison or learning language was found, the session and event counts, and how recently it was last active. The dashboard surfaces these directly.

Finally, title is a placeholder: the top three keywords from the thread's accumulated keywordSet, title-cased and joined with spaces, or "Untitled Thread" if there are none.

This is deliberately weak. Later in this guide, AI labeling replaces this heuristic title, along with summary and nextStep, with something grounded in what the thread is actually about (but the thread is fully usable without that step, too).

Putting it Together

buildThreads ties everything in this section together:

export async function buildThreads(): Promise<{ sessions: number; threads: number }> {
  const sessions = await getAllSessions();

  if (sessions.length === 0) {
    await clearThreads();
    return { sessions: 0, threads: 0 };
  }

  const ambient = detectAmbientDomains(sessions);

  const builders = clusterSessions(sessions, ambient);

  const substantive = builders.filter(
    (b) => !(b.sessions.length === 1 && b.sessions[0].events.length < 3)
  );

  const threads = substantive.map(scoreThread);

  await clearThreads();
  await putThreads(threads);

  console.table(
    threads.map((t) => ({
      title:        t.title,
      type:         t.type,
      status:       t.status,
      confidence:   t.confidence,
      distinctDays: t.distinctDays,
      sessions:     t.sessions.length,
      events:       t.sessions.reduce((n, s) => n + s.events.length, 0),
      keywords:     [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 5).join(", "),
    }))
  );

  return { sessions: sessions.length, threads: threads.length };
}

The order here matters. detectAmbientDomains runs once, over every session, before any clustering happens, since ambient detection needs the full picture of your browsing to know what counts as "every day".

clusterSessions then produces ThreadBuilders, which get filtered before scoring: a ThreadBuilder with exactly one session and fewer than three events is almost always a stray page load that didn't merge with anything, so it's dropped rather than becoming a thread with a confidence near zero.

Everything that survives gets scored by scoreThread, persisted, and printed via console.table, which is the tuning aid mentioned earlier. If you open the service worker's console after running this, every thread is laid out in a sortable table. This is the fastest way to spot a SIMILARITY_THRESHOLD that's too high or too low.

Checkpoint

Like the previous two sections, buildThreads doesn't have a UI yet. It'll get wired up to a "Build intent map" button alongside the other two when you design the dashboard later in this guide.

For now, confirm that src/pipeline/ambient.ts, the updated src/db/index.ts, and src/pipeline/threads.ts all build without errors, and that getDB() reports version 3 the next time the extension reloads. intent_threads should now be listed alongside raw_events and sessions in DevTools.

At this point, the entire core pipeline runs end to end, locally, with no API keys involved: your browsing history becomes raw events, raw events become sessions, and sessions become scored, classified intent threads.

Everything from here is optional and additive: cleaning up a source of self-referential noise this pipeline doesn't yet handle (which you probably want to look at and incorporate), then AI labeling, brand grounding, and the dashboard that ties it all together.

How to Clean Up Self-Referential Noise

Run the pipeline a few times against your own browsing and a strange kind of thread starts appearing: one made entirely of openloops itself.

The dashboard is a web page, so every time you open it to check your threads, that page load gets captured as an event. If you're also developing the extension, your localhost dev server and any private-network addresses end up in the data too.

The tool ends up watching itself use itself, and that self-reference pollutes the intent map in two distinct ways which are worth separating.

The Two Problems

The first problem is the extension's own pages. A Chrome extension's dashboard loads from a chrome-extension:// URL, and Chrome's own internal pages use chrome://. Left unfiltered, opening the openloops dashboard ten times in an afternoon produces ten events on a chrome-extension:// origin, which cluster happily into a thread about, essentially, looking at your threads.

This is circular and useless, and because you tend to open the dashboard often while the rest of your browsing is quieter, this self-thread can score deceptively high on recency and session count.

The second problem is local development infrastructure. If you're building the extension, or any local project, your history fills with localhost:5173, 127.0.0.1:8080, and maybe LAN addresses like 192.168.1.40. These are real page visits as far as Chrome is concerned, but they carry no browsing intent in the sense openloops cares about. Worse, they'd later be sent to context.dev during brand enrichment, where they can never resolve to anything and would only waste API credits.

Both problems share a root cause: the pipeline is capturing URLs that aren't really part of your browsing in the first place. The fix is to define what counts as a real, external web page once, and apply that definition everywhere a URL or domain enters the system.

One Definition, Applied Everywhere

The two helpers that do this, isHttpUrl and isLocalHost, were written back when you first built src/lib/util.ts. We deliberately introduced them early for exactly this moment.

isHttpUrl returns true only for http:// and https:// URLs, which excludes chrome-extension://, chrome://, about:, and file:// in one stroke. isLocalHost returns true for localhost, loopback and private IP ranges, and .local hostnames.

The thing that makes them effective is consistency: the same two functions guard every entry point, so the definition of "a real page" can never drift between one part of the pipeline and another. There are three such entry points.

Live capture, in src/background.ts, calls isHttpUrl before recording anything:

if (!isHttpUrl(url)) return;

The backfill, in src/pipeline/backfill.ts, applies the same guard to every history item before fetching its visits:

if (!item.url) return [];
if (!isHttpUrl(item.url)) return [];

And the noise filter, in src/pipeline/noise.ts, checks both helpers at the very top of isNoise, before any of its domain or title rules run:

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

Capture and backfill already screen out non-web URLs, so checking isHttpUrl a third time inside isNoise looks redundant, and in normal operation it is. The third check is a guarantee: if a stray non-web event ever reaches raw_events through some path you didn't anticipate (like a future capture mechanism, imported data, or a bug), it still can't survive into a session.

Each stage defends its own input rather than trusting that an earlier stage did its job. This is what keeps a single missed case from silently propagating all the way into the intent map.

Defending the Enrichment Boundary Too

The same isLocalHost check appears once more, in the brand enrichment step you'll build next, where domains get sent to context.dev. Even though isNoise already strips local addresses before sessionization, the enrichment function filters them again before making any network call:

const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

The reasoning is the same defense-in-depth idea, applied to a boundary where the cost of a mistake is higher. A local address that somehow reached a thread's domain list shouldn't just be useless noise in the UI. It should never leave your machine as part of an API request. Putting the filter directly at the network boundary means that guarantee holds regardless of what happened upstream.

Checkpoint

After loading the updated build, openloops should stop appearing in its own intent map. To verify, open the dashboard a handful of times, browse some real pages, then rebuild the pipeline: the chrome-extension:// self-thread should be gone, and no localhost or private-IP domains should appear in any thread's domain list.

If you inspect raw_events in DevTools, you may still see live-captured events from before this fix, since the backfill clears and rewrites events but live capture appends. Running a fresh "Scan my history" wipes and repopulates raw_events cleanly under the new rules.

With the pipeline now producing a clean intent map of genuinely external browsing, it's worth making those threads more legible.

Up to now, each thread's title is just its top three keywords stitched together, and there's no summary or suggested next step at all. The next section adds the first optional, key-gated layer: AI labeling with Claude.

How to Label Threads with Claude

A thread titled "Typescript Generics Handbook" is readable, but it's a description of the keywords – not of what you were trying to do. "Learning TypeScript's advanced type system" is the kind of label a person would actually write, and the difference between those two is the gap this section closes.

Claude reads each thread's keywords, domains, and sample page titles, and returns a real title, a one-sentence summary, a classification, and a concrete next step.

This is the first part of openloops that calls an external API and requires a key. Everything about its design is shaped by one constraint: the request has to survive real data, where a person might have thirty or forty threads, each carrying a dozen page titles.

The naïve version of this is to send all the threads in one request and ask for all the labels back. And that's exactly what the first implementation did. But it failed in a way worth walking through, because the fix is the most instructive part of the whole section.

Storing Keys Locally

Before any API call, the key needs somewhere to live. openloops keeps it in chrome.storage.local, which never syncs anywhere and never leaves the device. Create src/lib/settings.ts:

export async function getApiKey(): Promise<string | null> {
  const result = await chrome.storage.local.get("anthropicApiKey");
  return (result.anthropicApiKey as string) ?? null;
}

export async function setApiKey(key: string): Promise<void> {
  await chrome.storage.local.set({ anthropicApiKey: key });
}

The same file later grows parallel getters and setters for the context.dev key and the assistant's model and effort preferences, all following this identical shape. So it's enough to understand this one pair to understand all of them.

The First Version, and How it Broke

The first labeling implementation sent every thread to Claude in a single request: serialize all forty threads into one JSON payload, ask for a JSON array of forty labels in return, parse it, write it back. It worked perfectly with five or six threads during early testing, then silently produced nothing once a real history with thirty-plus threads went through it. There was no error or thrown exception, just threads that kept their old keyword titles as if the labeling had never run.

The cause was output token truncation. A request specifies max_tokens, the ceiling on how much the model may generate in response, and forty threads' worth of titles, summaries, and next steps is a lot of output. When the response hit that ceiling mid-generation, the JSON array was cut off partway through an opening [ and thirty complete objects followed by half of the thirty-first and no closing ]. JSON.parse on that throws, the catch block logged it and returned nothing, and because labeling was designed to fail gracefully and leave existing titles intact, the failure was invisible from the UI.

Two design changes came out of this, and both are in the final code: split the work into small batches so no single response can grow large enough to truncate, and make the parsing resilient enough that one bad batch can't take down the whole run.

Batching the Requests

Create src/pipeline/label.ts, starting with the per-batch request function:

import { getAllThreads, putThreads, getAllBrands } from "../db/index";
import type { IntentThread } from "../types";

interface ThreadDescriptor {
  id: string;
  keywords: string[];
  domains: string[];
  sampleTitles: string[];
  domainContext: string[];
}

interface LabelResult {
  id: string;
  title: string;
  summary: string;
  type: string;
  nextStep: string;
}

const VALID_TYPES: ReadonlySet<IntentThread["type"]> = new Set([
  "buying",
  "research",
  "learning",
  "planning",
  "unclassified",
]);

const BATCH_SIZE = 10;
const MAX_TOKENS_PER_BATCH = 4000;

async function callClaudeBatch(
  apiKey: string,
  systemPrompt: string,
  batch: ThreadDescriptor[],
): Promise<LabelResult[] | null> {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": apiKey,
      "anthropic-version": "2023-06-01",
      "anthropic-dangerous-direct-browser-access": "true",
    },
    body: JSON.stringify({
      model: "claude-haiku-4-5-20251001",
      max_tokens: MAX_TOKENS_PER_BATCH,
      system: systemPrompt,
      messages: [
        {
          role: "user",
          content: JSON.stringify(batch),
        },
      ],
    }),
  });

  if (!response.ok) {
    let body = "";
    try { body = (await response.text()).slice(0, 400); } catch { }
    console.error(
      `[openloops] label: API request failed\n` +
      `  → HTTP \({response.status} \){response.statusText}\n` +
      `  body: ${body || "(empty)"}`,
    );
    if (response.status === 401) {
      throw new Error("Invalid API key. Check your Anthropic API key and try again.");
    }
    throw new Error(`API request failed: \({response.status} \){response.statusText}`);
  }

  const data = await response.json();
  const raw: string = data.content[0].text;

  const cleaned = raw
    .trim()
    .replace(/^```(?:json)?\s*/, "")
    .replace(/```\s*$/, "")
    .trim();

  try {
    return JSON.parse(cleaned);
  } catch (err) {
    console.error(`[openloops] label: parse error: ${err instanceof Error ? err.message : String(err)}`);
    console.error(`[openloops] label: raw tail (last 400 chars):\n${raw.slice(-400)}`);
    return null;
  }
}

BATCH_SIZE of 10 with MAX_TOKENS_PER_BATCH of 4000 is the direct answer to the truncation problem. Ten threads' worth of labels comfortably fits inside 4000 output tokens with room to spare, so a batch can't hit the ceiling and get cut off. A history with forty threads becomes four independent requests rather than one oversized one.

The request itself uses raw fetch rather than Anthropic's TypeScript SDK, because the SDK isn't built to run in a browser or extension context.

Browser-originated calls to the Anthropic API also require the anthropic-dangerous-direct-browser-access header, which is what opts into this usage pattern. The model is Claude Haiku, the fastest and cheapest in the lineup, which is well-matched to a high-volume, structured-output task like this one where you're making several calls and want them quick.

The error handling splits into two deliberately different behaviors. An HTTP-level failure (a 401 from a bad key, a 429 from rate limiting) throws, because every subsequent batch would fail the same way and there's no point continuing. A parse failure, by contrast, returns null rather than throwing, so the caller can skip just that one batch and keep going with the rest.

The fence-stripping before JSON.parse handles a common real-world wrinkle: models sometimes wrap JSON output in a Markdown code fence (```json), even when asked for raw JSON. The two .replace calls strip a leading fence and a trailing fence if present, tolerating surrounding whitespace, so a response comes through whether or not it arrived wrapped.

When parsing still fails, the catch logs the last 400 characters of the raw response, which is precisely where you'd see the truncation signature of a cut-off array, the diagnostic that would have made the original bug obvious in minutes.

Building the Prompt and Merging Results

The public labelThreads function builds the descriptors, runs the batches, and merges what comes back:

export async function labelThreads(apiKey: string): Promise<{ labeled: number }> {
  const threads = await getAllThreads();
  if (threads.length === 0) return { labeled: 0 };

  const allBrands = await getAllBrands();
  const brandMap = new Map(allBrands.map((b) => [b.domain, b]));

  const descriptors: ThreadDescriptor[] = threads.map((t) => {
    const keywords = [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 8);
    const domains  = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5);
    const titles   = [...new Set(t.sessions.flatMap((s) => s.events.map((e) => e.title)))].slice(0, 20);

    const domainContext = domains
      .map((d) => {
        const brand = brandMap.get(d);
        if (!brand || !brand.name) return null;
        let line = `\({d}: \){brand.name}`;
        if (brand.description) line += ` — ${brand.description}`;
        if (brand.industry)    line += ` (${brand.industry})`;
        return line;
      })
      .filter((s): s is string => s !== null);

    return { id: t.id, keywords, domains, sampleTitles: titles, domainContext };
  });

  const systemPrompt = `You label browsing intent threads. Return ONLY a JSON array — no markdown fences, no explanation.
Each element: { "id": "<thread id>", "title": "<3-6 word title>", "summary": "<1 sentence>", "type": "<buying|research|learning|planning|unclassified>", "nextStep": "<one concrete, specific action to move this thread forward or close the loop>" }
The nextStep must be grounded in what the person was actually looking at. Be specific — name the actual decision, comparison, or action (e.g. "Decide between MacBook Pro and Dell XPS — your open question was battery life") rather than generic advice ("continue researching"). Use the sampleTitles and domainContext to ground it.
Each thread descriptor may include a "domainContext" array of company descriptions for the sites visited. When present, use these to produce sharper, more specific titles, summaries, and next steps grounded in what each company actually does.
Respond with exactly one array covering every thread in the request.`;

  const allResults: LabelResult[] = [];
  let failedBatches = 0;
  for (let i = 0; i < descriptors.length; i += BATCH_SIZE) {
    const batch = descriptors.slice(i, i + BATCH_SIZE);
    const results = await callClaudeBatch(apiKey, systemPrompt, batch);
    if (results === null) {
      failedBatches++;
      continue;
    }
    allResults.push(...results);
  }

  const byId = new Map(allResults.map((r) => [r.id, r]));

  let labeled = 0;
  const updated = threads.map((t) => {
    const label = byId.get(t.id);
    if (!label) return t;

    const type = VALID_TYPES.has(label.type as IntentThread["type"])
      ? (label.type as IntentThread["type"])
      : t.type;

    labeled++;
    return {
      ...t,
      title:    label.title    || t.title,
      summary:  label.summary  || undefined,
      nextStep: label.nextStep || undefined,
      type,
    };
  });

  await putThreads(updated);
  return { labeled };
}

Each thread is compressed into a ThreadDescriptor carrying only what Claude needs to label it: up to eight keywords, five domains, and twenty sample page titles, capped so a thread with hundreds of events doesn't bloat the payload.

The domainContext field is the hook for the brand-grounding step covered in the next section. It's empty for now since no brands have been fetched yet, which is exactly why labeling works fine on its own and gets sharper once grounding is added.

The merge step is where a failed batch costs you only its own threads. Results come back as a flat list across all successful batches, indexed by thread id into byId.

Then every thread is walked: if a label came back for it, the AI title, summary, next step, and type are merged in, with the returned type validated against VALID_TYPES and falling back to the heuristic type if the model returned something unexpected. If no label came back, because that thread's batch failed to parse, the thread is returned untouched, keeping the keyword title and heuristic classification it already had.

A single failed batch costs you ten threads' worth of polish, not the entire run, and never corrupts a thread with malformed data.

Notice that title, summary, and nextStep all guard against empty strings with || t.title and || undefined. A thread always has a usable title even if the model returned a blank one, and summary and nextStep stay undefined rather than becoming empty strings. This keeps the dashboard's "does this thread have a summary?" checks honest.

Checkpoint

Labeling needs a key and a button, both of which arrive with the dashboard later in this guide, so a full end-to-end test waits until then.

What you can verify now is that src/lib/settings.ts and src/pipeline/label.ts compile, and that the request shape is correct by calling labelThreads with a real key from a temporary test harness if you want immediate feedback. When it runs against built threads, the console will show batch progress, and your threads' titles in IndexedDB will change from keyword fragments to readable phrases, with summary and nextStep fields appearing for the first time.

The labels are already a large improvement, but they're working from keywords and bare domain names. This means a thread built around mastra.ai and langchain.com has no idea those are AI agent frameworks. It only sees two domain strings.

The next section closes that gap by resolving domains into real company descriptions before labeling. This is the grounding step that gives the AI something concrete to reason about.

How to Ground Labels with context.dev

This is the most distinctive idea in openloops, so it's worth stating plainly before any code: instead of asking the model to label a thread from keywords and bare domain names, openloops first resolves each domain into a real company description – what the company is, what industry it's in, what it actually does – and feeds those descriptions into the labeling prompt. The model labels the thread knowing that mastra.ai and langchain.com are both AI agent frameworks, rather than seeing two opaque strings it has to guess about.

A thread whose keywords are "mastra langchain sholajegede" produces, ungrounded, a title like "Mastra Langchain Sholajegede", a literal echo of the keywords. Grounded with the knowledge that those domains are competing agent frameworks, the same thread becomes "Benchmarking Mastra against LangChain", a title that names the actual intent.

The raw material for a good label was always there in the browsing. What was missing was the context to interpret it, and that context is exactly what a brand-intelligence API provides.

What the API Returns

openloops uses context.dev, which resolves a domain into a structured brand record: company name, a one-line description, industry classification, brand colors, and logo URLs. The grounding step needs the name, description, and industry, while the logo and colors get used later by the dashboard to render domain chips.

This step is entirely optional: the labeling from the previous section works without it, and grounding simply makes the output sharper when a context.dev key is present.

Like the Anthropic key, the context.dev key lives in chrome.storage.local, via the same getter/setter pattern in src/lib/settings.ts:

export async function getContextKey(): Promise<string | null> {
  const result = await chrome.storage.local.get("contextDevApiKey");
  return (result.contextDevApiKey as string) ?? null;
}

export async function setContextKey(key: string): Promise<void> {
  await chrome.storage.local.set({ contextDevApiKey: key });
}

Brand records also need a place to be cached, since resolving the same domain twice is wasteful and costs API credits. Bump DB_VERSION to 4 and add a domain_brands store keyed by domain:

import type { RawEvent, Session, IntentThread, Brand } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: { key: string; value: RawEvent; indexes: { by_visitedAt: number } };
  sessions: { key: string; value: Session; indexes: { by_startedAt: number } };
  intent_threads: { key: string; value: IntentThread; indexes: { by_lastSeen: number } };
  domain_brands: {
    key: string;
    value: Brand;
  };
}

const DB_VERSION = 4;

Inside the upgrade callback, the new store is added with the same guard as the others, and domain_brands is keyed on domain rather than id because a domain is its own natural unique key:

if (!db.objectStoreNames.contains("domain_brands")) {
  db.createObjectStore("domain_brands", { keyPath: "domain" });
}

The matching helpers add one that's specific to caching, getCachedDomains. This returns the set of domains already resolved so the enrichment step can skip them:

export async function getBrand(domain: string): Promise<Brand | undefined> {
  const db = await getDB();
  return db.get("domain_brands", domain);
}

export async function putBrands(brands: Brand[]): Promise<void> {
  if (brands.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("domain_brands", "readwrite");
  await Promise.all([...brands.map((b) => tx.store.put(b)), tx.done]);
}

export async function getAllBrands(): Promise<Brand[]> {
  const db = await getDB();
  return db.getAll("domain_brands");
}

export async function getCachedDomains(): Promise<Set<string>> {
  const db = await getDB();
  const keys = await db.getAllKeys("domain_brands");
  return new Set(keys);
}

Fetching One Brand

Create src/pipeline/enrich.ts. The core is a function that resolves a single domain, and most of its length is there to make sure a slow or failing lookup can never hang or crash the whole step:

import { getCachedDomains, putBrands } from "../db/index";
import { isLocalHost } from "../lib/util";
import type { Brand } from "../types";

const API_BASE        = "https://api.context.dev/v1";
const LOGO_LINK_BASE  = "https://logos.context.dev";

const REQUEST_TIMEOUT_MS = 15_000;
const BATCH_SIZE     = 3;
const BATCH_DELAY_MS = 2_000;

interface FetchResult {
  brand: Brand | null;
  errorCode?: string;
}

async function fetchBrand(domain: string, contextKey: string): Promise<FetchResult> {
  const url = `\({API_BASE}/brand/retrieve?domain=\){encodeURIComponent(domain)}`;
  const headers = { Authorization: `Bearer ${contextKey}` };

  async function attempt(): Promise<Response> {
    const ctrl = new AbortController();
    const tid  = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    try {
      return await fetch(url, { headers, signal: ctrl.signal });
    } finally {
      clearTimeout(tid);
    }
  }

  try {
    let res = await attempt();

    if (res.status === 408) {
      res = await attempt();
    }

    if (!res.ok) {
      let body = "";
      try { body = (await res.text()).slice(0, 400); } catch { }
      console.error(`[openloops] enrich: HTTP \({res.status} for "\){domain}" — ${body}`);
      return { brand: null, errorCode: String(res.status) };
    }

    let data: { status?: string; brand?: Record<string, unknown> };
    try {
      data = await res.json();
    } catch (e) {
      return { brand: null, errorCode: "parse" };
    }

    if (data.status !== "ok" || !data.brand) {
      return { brand: null, errorCode: "shape" };
    }

    const b = data.brand as {
      title?:        string;
      description?:  string;
      colors?:       { hex?: string }[];
      logos?:        { url?: string }[];
      industries?:   { eic?: { industry?: string; subindustry?: string }[] };
    };

    const logoUrl =
      b.logos?.[0]?.url ||
      `\({LOGO_LINK_BASE}?domain=\){encodeURIComponent(domain)}`;

    return {
      brand: {
        domain,
        name:        b.title                          ?? domain,
        description: b.description                    ?? "",
        industry:    b.industries?.eic?.[0]?.industry ?? "",
        logoUrl,
        brandColor:  b.colors?.[0]?.hex               ?? "",
      },
    };

  } catch (err) {
    if (err instanceof Error && err.name === "AbortError") {
      return { brand: null, errorCode: "timeout" };
    }
    return { brand: null, errorCode: "network" };
  }
}

The request authenticates with a bearer token and hits a single brand/retrieve endpoint. The attempt inner function wraps each call in an AbortController with a 15-second timeout, so a stalled connection aborts itself rather than hanging the enrichment step indefinitely.

The finally clears the timer whether the request succeeds, fails, or aborts. A 408 response from context.dev means a cold cache miss on their side, which their documentation says to retry once, so a single retry handles it before giving up.

The response is unpacked defensively at every level: a non-OK status returns a FetchResult with the HTTP code, a body that won't parse returns a "parse" error, and a response whose shape isn't what's expected returns a "shape" error.

When the brand record does come through, each field falls back to a sensible default if absent, the company name falls back to the domain itself, the description and industry to empty strings, and the logo to context.dev's keyless logo CDN if the record carries no logo URL.

Every failure path returns { brand: null, errorCode } rather than throwing, which is what lets the batch driver above it treat a single domain's failure as a skip rather than a crash.

Enriching Domains in Batches

The public enrichDomains function resolves a list of domains, skipping ones already cached and respecting the API's rate limit:

export async function enrichDomains(
  contextKey: string,
  domains: string[],
): Promise<{ enriched: number; failed: number; error?: string }> {
  const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

  let cached: Set<string>;
  try {
    cached = await getCachedDomains();
  } catch (err) {
    return { enriched: 0, failed: 0, error: "DB error" };
  }

  const toFetch = unique.filter((d) => !cached.has(d));
  if (toFetch.length === 0) return { enriched: 0, failed: 0 };

  let enriched = 0;
  let failed   = 0;
  let firstErrorCode: string | undefined;

  for (let i = 0; i < toFetch.length; i += BATCH_SIZE) {
    const batch   = toFetch.slice(i, i + BATCH_SIZE);
    const results = await Promise.all(batch.map((d) => fetchBrand(d, contextKey)));

    const brands = results.map((r) => r.brand).filter((b): b is Brand => b !== null);

    for (const r of results) {
      if (!r.brand) {
        failed += 1;
        if (!firstErrorCode) firstErrorCode = r.errorCode;
      }
    }

    if (brands.length > 0) {
      try {
        await putBrands(brands);
        enriched += brands.length;
      } catch (err) {
        failed += brands.length;
      }
    }

    if (i + BATCH_SIZE < toFetch.length) {
      await new Promise<void>((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
    }
  }

  let error: string | undefined;
  if (firstErrorCode) {
    const map: Record<string, string> = {
      "401":     "401 — invalid key",
      "403":     "403 — check key permissions",
      "429":     "429 — rate limited, try again later",
      "timeout": "request timeout (15 s)",
      "network": "unreachable — check network/CORS",
    };
    error = map[firstErrorCode] ?? firstErrorCode;
  }

  return { enriched, failed, error };
}

The function opens by stripping local addresses with isLocalHost, the enrichment-boundary guard discussed in the self-referential noise section. This means that a dev server can never be sent to context.dev even if it slipped into a thread's domain list. It then removes already-cached domains via getCachedDomains, so re-running enrichment only ever fetches domains it hasn't seen. This keeps credit usage proportional to new browsing rather than total browsing.

The remaining domains are fetched three at a time, with a two-second pause between batches. This keeps the request rate well under the API's limit without making the user wait through a long serial queue.

Failures are tallied rather than thrown: a domain that fails to resolve increments failed and records its error code, but the loop carries on. The first error code encountered gets mapped to a human-readable message at the end so the UI can show something useful, such as an invalid-key or rate-limit notice.

The whole function returns counts rather than raising, which matters because the dashboard runs enrichment immediately before labeling, and a problem fetching brands should never prevent the labeling that follows it.

How Grounding Feeds Back into Labeling

Grounding connects back to labelThreads from the previous section, which already builds a domainContext array for each thread by looking up every domain in the brand cache:

const domainContext = domains
  .map((d) => {
    const brand = brandMap.get(d);
    if (!brand || !brand.name) return null;
    let line = `\({d}: \){brand.name}`;
    if (brand.description) line += ` — ${brand.description}`;
    if (brand.industry)    line += ` (${brand.industry})`;
    return line;
  })
  .filter((s): s is string => s !== null);

Before enrichment runs, the brand cache is empty, every lookup returns nothing, domainContext is an empty array, and the prompt falls back to keywords and domain names alone.

After enrichment, the same code produces lines like mastra.ai: Mastra — TypeScript framework for building AI agents (Developer Tools), and the labeling prompt's instruction to use domainContext "to produce sharper, more specific titles, summaries, and next steps" finally has something to work with.

The two steps are decoupled by design: labeling never requires grounding, but grounding measurably improves labeling. This is why the dashboard runs them in sequence as a single "enrich, then label" action.

Checkpoint

Like the labeling step, enrichment is exercised through the dashboard, so the full path waits for the dashboard section. For now, confirm that src/pipeline/enrich.ts and the updated src/db/index.ts compile, and that getDB() reports version 4 with domain_brands present in DevTools.

Once it runs against real threads with a context.dev key, the domain_brands store fills with cached records, and your thread labels should noticeably sharpen. The clearest single demonstration will be any thread built around niche or technical domains whose names don't, on their own, reveal what they are.

Every piece of the engine now exists: capture, sessions, clustering, scoring, labeling, and grounding. What's missing is the surface that drives them and shows the results.

The next section builds the dashboard, the three-column React interface with its onboarding flow and pipeline state machine, that turns this pipeline into something a person actually uses.

How to Design the Dashboard

The dashboard is a single React component tree rendered into the full-tab page you wired up at the very start when you set options_page in the manifest.

It does three jobs: it drives the pipeline (the buttons that run scanning, session-building, thread-building, and labeling), it displays the resulting intent map (threads grouped by status), and it hosts the assistant covered in the next section.

This section focuses on the structure and the one piece of genuinely interesting logic: the state machine that decides which pipeline button is live at any moment. We'll treat the styling at a summary level here, since it's mostly conventional CSS.

The Three-Column Layout

src/dashboard/App.tsx lays out three columns inside a flex shell. The left rail holds the pipeline controls, the API-key inputs, and the status filter. The center column is the main content: either the onboarding welcome screen or the intent map of threads. The right column holds overview statistics and the assistant chat.

┌──────────────┬───────────────────────────┬──────────────────┐
│  LEFT RAIL   │       MAIN COLUMN         │  RIGHT COLUMN    │
│              │                           │                  │
│  Pipeline    │  Welcome screen           │  Overview stats  │
│   · Scan     │    — or —                 │                  │
│   · Sessions │  Intent map:              │  Assistant chat  │
│   · Threads  │   ACTIVE   threads        │   · messages     │
│              │   STALLED  threads        │   · composer     │
│  Keys        │   DORMANT  threads        │   · model/effort │
│  Filter      │                           │                  │
└──────────────┴───────────────────────────┴──────────────────┘

Each thread renders as a card showing its title, type and status pills, the AI summary, the next-step row with a Resume button, a confidence bar, and a collapsible details section with domains, keywords, and signals.

The cards are grouped into ACTIVE, STALLED, and DORMANT sections, sorted by confidence within each group. The threads most worth acting on rise to the top of the most urgent group.

The styling lives in src/dashboard/app.css and is conventional: a dark theme defined through CSS custom properties (a near-black background, a single orange accent at --accent: #ff5c33, a small scale of grays for text and borders), a monospace font for labels and metadata, and a sans-serif for content.

The design choices that matter for usability are the status-based color coding (the accent for active, a muted amber for stalled, gray for dormant) and the confidence bar's width mapping directly to the thread's confidence score.

None of the CSS is load-bearing for understanding the build, so rather than reproduce it, the rest of this section focuses on the logic the styling sits on top of.

The Pipeline State Machine

The pipeline has a strict order: you can't build sessions before scanning history, and you can't build threads before building sessions. The dashboard encodes this as a small state machine, and getting it right is what makes the interface feel guided rather than confusing. Every button is either disabled (its input doesn't exist yet), highlighted as the next action to take, or done (re-runnable, but no longer the obvious next step).

type PipelineState = "disabled" | "next" | "done";

function pipelineStates(
  hasScanned: boolean,
  eventCount: number | null,
  sessionCount: number | null,
  threadCount: number | null,
): { scan: PipelineState; sessions: PipelineState; threads: PipelineState } {
  const hasEvents   = (eventCount   ?? 0) > 0;
  const hasSessions = (sessionCount ?? 0) > 0;
  const hasThreads  = (threadCount  ?? 0) > 0;

  if (!hasScanned)  return { scan: "next", sessions: "disabled", threads: "disabled" };
  if (!hasSessions) return { scan: "done", sessions: hasEvents ? "next" : "disabled", threads: "disabled" };
  if (!hasThreads)  return { scan: "done", sessions: "done", threads: "next" };
  return { scan: "done", sessions: "done", threads: "done" };
}

The function reads the presence of data at each stage and returns the state of all three buttons. Before any scan, only Scan is live, marked next, while the other two are disabled.

Once events exist but sessions don't, Scan flips to done and Sessions becomes next. Once sessions exist but threads don't, Threads becomes next. Once all three stages have produced output, everything is done, every step re-runnable but none demanding attention. The cascade walks the pipeline in order and lights up exactly one next action at a time, which is what turns a row of three buttons into a guided sequence.

The first parameter, hasScanned, is more subtle than a simple count. It's where a piece of plumbing from the very first capture section pays off.

The check can't just be "are there any events," because live capture starts populating raw_events the moment the extension is installed. There would always be events, and the onboarding would skip straight past the Scan step before the user had ever scanned.

The fix is the source field on every RawEvent, set to "backfill" or "live" back when you built capture. hasScanned comes from a dedicated query that checks specifically for backfill events:

export async function hasBackfillEvents(): Promise<boolean> {
  const db = await getDB();
  let cursor = await db.transaction("raw_events", "readonly").store.openCursor();
  while (cursor) {
    if (cursor.value.source === "backfill") return true;
    cursor = await cursor.continue();
  }
  return false;
}

This walks raw_events until it finds a single event with source === "backfill", returning early the moment it does. Live-captured events alone never satisfy it, so "Scan my history" stays lit as the first step until the user actually runs a backfill, which is the correct onboarding behavior. The seemingly minor decision to tag each event with its origin, made several sections ago, is what makes this distinction possible now.

Driving the Welcome Screen from the Same Machine

A first-time user with no threads sees a centered welcome screen instead of an empty intent map. But rather than give that screen its own separate logic, the dashboard drives it from the same pipelineStates output. Whichever step is currently next determines which single call-to-action the welcome screen shows:

let welcomeStep: 1 | 2 | 3 = 1;
let welcomeCtaLabel = "Scan my history";
let welcomeCtaClick = handleScan;
if (scanState === "next") {
  welcomeStep = 1;
  welcomeCtaLabel = scanning ? "Scanning…" : "Scan my history";
  welcomeCtaClick = handleScan;
} else if (sessionsState === "next") {
  welcomeStep = 2;
  welcomeCtaLabel = buildingSessions ? "Building…" : "Build sessions";
  welcomeCtaClick = handleBuildSessions;
} else if (threadsState === "next") {
  welcomeStep = 3;
  welcomeCtaLabel = buildingThreads ? "Building…" : "Build your intent map";
  welcomeCtaClick = handleBuildThreads;
}

The welcome screen's single button always mirrors the rail's next action, so a user can move through scan, build sessions, and build threads by clicking one prominent button three times. The moment threads exist, the welcome screen is replaced by the intent map. The rail and the welcome screen never disagree about what to do next, because both read from the same source of truth.

Wiring the Handlers

The handlers themselves are thin: each runs a pipeline stage, then refreshes the component's view of the database. The action that runs grounding and labeling together is the one worth seeing, because it puts into practice the decoupling described in the previous two sections:

async function handleEnrichAndLabel() {
  setLabelError(null);
  setEnrichError(null);

  if (contextKey.trim() && contextKeySaved) {
    setEnriching(true);
    try {
      const allDomains = [...new Set(
        threads.flatMap((t) => t.sessions.flatMap((s) => s.domains))
      )];
      const result = await enrichDomains(contextKey.trim(), allDomains);
      if (result.error) setEnrichError(`context.dev: ${result.error}`);
      if (result.enriched > 0) {
        const all = await getAllBrands();
        setBrands(new Map(all.map((b) => [b.domain, b])));
      }
    } catch (err) {
      setEnrichError(`context.dev: ${err instanceof Error ? err.message : "unknown error"}`);
    } finally {
      setEnriching(false);
    }
  }

  setLabeling(true);
  try {
    await labelThreads(apiKey.trim());
    setThreads(await getAllThreads());
  } catch (err) {
    setLabelError(err instanceof Error ? err.message : "Labeling failed.");
  } finally {
    setLabeling(false);
  }
}

Enrichment runs only if a context.dev key is present, and it's wrapped so that any failure (like a network error, a bad key, or a rate limit) sets an error message but never stops execution. Labeling then runs unconditionally afterward, outside the enrichment block, so it proceeds whether enrichment succeeded, failed, or was skipped entirely for lack of a key.

That structure is the decoupling from the grounding section made concrete: grounding improves labeling when it works, and labeling degrades gracefully to keyword-and-domain context when it doesn't.

The enrichment error surfaces in amber rather than red, because it's a warning (labeling still happened) rather than a blocking failure. This is a small UI cue that matches the actual severity of what went wrong.

The Resume Button

One interaction ties the intent map back to live browsing. Each thread card has a Resume button that reopens the pages you were on, so acting on a thread is one click rather than a hunt through history:

const RESUME_SKIP_DOMAINS = new Set([
  "google.com", "youtube.com", "bing.com", "duckduckgo.com",
  "gmail.com", "mail.google.com",
]);

function resumeThread(thread: IntentThread): void {
  const seen = new Set<string>();
  const urls: string[] = [];

  const sorted = thread.sessions
    .flatMap((s) => s.events)
    .sort((a, b) => b.visitedAt - a.visitedAt);

  for (const ev of sorted) {
    if (RESUME_SKIP_DOMAINS.has(ev.domain)) continue;
    if (seen.has(ev.url)) continue;
    seen.add(ev.url);
    urls.push(ev.url);
    if (urls.length >= 3) break;
  }

  urls.forEach((url, i) => {
    chrome.tabs.create({ url, active: i === 0 });
  });
}

Resume sorts the thread's events newest-first, skips search engines and webmail (which are waypoints rather than destinations you'd want to return to), dedupes by URL, and opens the three most recent meaningful pages. The first is the active tab and the rest are in the background. It's a small feature, but it's the thing that makes a thread feel like a place you can return to rather than a record of where you've been.

Checkpoint

With the dashboard wired up, the entire pipeline is finally usable end to end through the interface. Reload the extension, open the dashboard, and you should see the welcome screen prompting you to scan.

Click through scan, build sessions, build your intent map, and the threads should appear, grouped by status. Add an Anthropic key, optionally a context.dev key, and click "Label & enrich" to see titles and next steps sharpen. The full loop you've built across every previous section now runs from a single screen.

What remains is the conversational layer on the right: an AI assistant that can reason across all your threads at once and answer questions like "what should I close this week?" The next section builds it.

How to Build the AI Assistant

The labeling step asks Claude to describe one thread at a time. The assistant asks something harder: to reason across all of your threads together and answer open-ended questions about them, like what to close this week, what you've stalled on longest, or how to finish a particular one.

This is a chat interface, but a constrained one – grounded entirely in your own thread data, so its answers reference real threads by name rather than offering generic productivity advice.

The whole design rests on one idea: a chat assistant is only as good as the context it's given. So most of the work here is in building the right grounding context for each message, not in the chat mechanics themselves.

Grounding the Conversation

Before any message goes to Claude, the assistant assembles a system prompt describing the user's threads. It does this in one of two modes, depending on whether the user has clicked into a specific thread.

With no thread selected, it builds a compact digest of every thread. With one selected, it gives rich detail on that thread and a brief list of the others.

function buildGroundingContext(
  threads: IntentThread[],
  brands: Map<string, Brand>,
  selectedThread: IntentThread | null,
): string {
  if (!selectedThread) {
    const digest = threads
      .map((t) => {
        const domains = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5).join(", ");
        return `- \({t.title} (\){t.status}, \({t.type}): \){t.summary ?? "no summary yet"} | next: \({t.nextStep ?? "none"} | domains: \){domains || "none"}`;
      })
      .join("\n");

    return `\({SYSTEM_INSTRUCTION}\n\nHere is a digest of all the user's open intent threads:\n\){digest || "(no threads yet)"}`;
  }

  const keywords = [...new Set(selectedThread.sessions.flatMap((s) => s.keywords))].slice(0, 10).join(", ");
  const domains = [...new Set(selectedThread.sessions.flatMap((s) => s.domains))].slice(0, 5);

  const domainLines = domains
    .map((d) => {
      const brand = brands.get(d);
      if (brand?.description) return `- \({d}: \){brand.name} — ${brand.description}`;
      return `- ${d}`;
    })
    .join("\n");

  const sampleTitles = [...new Set(selectedThread.sessions.flatMap((s) => s.events.map((e) => e.title)))]
    .slice(0, 20)
    .map((t) => `- ${t}`)
    .join("\n");

  const otherTitles = threads
    .filter((t) => t.id !== selectedThread.id)
    .map((t) => t.title)
    .join(", ");

  return `${SYSTEM_INSTRUCTION}

The user is focused on this thread:
Title: ${selectedThread.title}
Status: ${selectedThread.status}
Type: ${selectedThread.type}
Summary: ${selectedThread.summary ?? "none"}
Next step: ${selectedThread.nextStep ?? "none"}
Keywords: ${keywords || "none"}

Domains visited:
${domainLines || "(none)"}

Recent page titles:
${sampleTitles || "(none)"}

For context, the user's other open threads are: ${otherTitles || "none"}.`;
}

The two modes match the two kinds of questions people ask. A question like "what should I close this week?" is about the whole set, so the digest mode gives Claude a one-line summary of every thread. This is enough breadth to compare and prioritize across all of them.

A question like "how do I finish this one?", on the other hand, is about a single thread, so the focused mode trades breadth for depth. It hands over that thread's keywords, its domains with their brand descriptions, and up to twenty real page titles, while still naming the other threads so Claude knows what else is in play.

The focused mode is where brand grounding shows up again. The same brand records fetched during enrichment get woven into the domain list, so when the user asks about a thread, Claude sees mastra.ai: Mastra — TypeScript framework for building AI agents rather than a bare domain. This is the identical grounding principle from labeling, now applied to conversation.

The system instruction that prefixes both modes pins the assistant to its data:

const SYSTEM_INSTRUCTION =
  `You are the assistant inside "openloops", a browser extension that reconstructs ` +
  `the user's browsing history into "intent threads" — decisions, research, or ` +
  `plans they started and haven't closed. Help the user understand and act on ` +
  `these open loops. Be concrete: reference the actual threads by name and ` +
  `suggest real next actions. You are grounded only in the thread data provided ` +
  `below — if the user asks about something not present in it, say so plainly ` +
  `rather than guessing.`;

The final instruction is the important one: telling the model to admit when something isn't in its data, rather than inventing a plausible answer, is what keeps the assistant trustworthy when a user asks about a thread that doesn't exist or a detail the data doesn't contain.

Sending a Message

The send function rebuilds the grounding context fresh on every message. The assistant always reflects the current state of the threads (including any that changed since the conversation started) and posts the whole message history to Claude:

async function send(text: string) {
  const trimmed = text.trim();
  if (!trimmed || sending) return;

  if (!keySaved) {
    setError("Add your Anthropic key above to chat.");
    return;
  }

  setError(null);
  const nextMessages: Message[] = [...messages, { role: "user", content: trimmed }];
  setMessages(nextMessages);
  setInput("");
  setSending(true);

  try {
    const systemPrompt = buildGroundingContext(threads, brands, selectedThread);
    const maxTokens = EFFORT_OPTIONS.find((e) => e.id === effort)?.maxTokens ?? 1024;

    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true",
      },
      body: JSON.stringify({
        model,
        max_tokens: maxTokens,
        system: systemPrompt,
        messages: nextMessages.map((m) => ({ role: m.role, content: m.content })),
      }),
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error("Invalid API key. Check your Anthropic API key and try again.");
      }
      throw new Error(`API request failed: \({response.status} \){response.statusText}`);
    }

    const data: { content: AnthropicContentBlock[] } = await response.json();
    const reply = data.content
      .filter((b) => b.type === "text" && b.text)
      .map((b) => b.text)
      .join("");

    setMessages((prev) => [...prev, { role: "assistant", content: reply || "(empty response)" }]);
  } catch (err) {
    setError(err instanceof Error ? err.message : "Something went wrong.");
  } finally {
    setSending(false);
  }
}

The mechanics mirror the labeling request, the same endpoint, the same browser-access header, and the same 401-aware error handling, since both talk to the same API from the same constrained environment. The user's message gets appended to the running messages array, the full array is sent so the model has the conversation so far, and the assembled grounding context rides along as the system prompt. The reply is extracted by concatenating the text blocks from the response, with a fallback string if the model returned nothing usable.

Rebuilding buildGroundingContext on every send rather than once per conversation is a deliberate choice: if the user re-runs the pipeline or labels their threads mid-conversation, the next message reflects the updated data automatically, with no stale snapshot from when the chat began.

Model and Effort Controls

The assistant exposes two selectors: which model to use and how much depth to allow. Both are persisted to chrome.storage.local through the same settings pattern as the keys:

const MODEL_OPTIONS = [
  { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 — fastest" },
  { id: "claude-sonnet-4-6",          label: "Sonnet 4.6 — balanced" },
  { id: "claude-opus-4-8",            label: "Opus 4.8 — most capable" },
];

const EFFORT_OPTIONS = [
  { id: "low",    label: "Low",    maxTokens: 512 },
  { id: "medium", label: "Medium", maxTokens: 1024 },
  { id: "high",   label: "High",   maxTokens: 2048 },
];

The model selector spans the speed-versus-capability range: Haiku for quick answers, Opus for harder reasoning over a tangled set of threads. The effort selector maps to max_tokens, controlling how long an answer the model may produce. This is a reasonable proxy for response depth given the Messages API has no dedicated depth control. A user wanting a one-line answer picks Low, while one wanting a reasoned, prioritized plan picks High.

Rendering Replies and the Empty State

The assistant renders Claude's replies as Markdown, since the model naturally formats prioritized lists and step-by-step suggestions with headings and bullets. This would look like raw asterisks and hashes if rendered as plain text. Using react-markdown, the reply component is essentially <ReactMarkdown>{m.content}</ReactMarkdown> for assistant messages, with user messages rendered as plain text. The accompanying styles target the rendered Markdown elements to match the dashboard's type scale.

Before any conversation starts, the panel shows an empty state with a one-line explanation and a few suggested prompts as clickable chips, "What should I close this week?", "Summarize my open loops", "What have I stalled on longest?". These both demonstrate what the assistant can do and give a one-click way to start.

The suggested prompts shift slightly when a thread is focused, offering "How do I finish this one?" in place of the whole-set summary, matching the focused grounding mode.

A privacy line sits permanently below the composer, stating that chats send thread titles and summaries to Anthropic and nothing else leaves the device. This is the same honest disclosure principle applied throughout, placed where the user will see it before they type.

Checkpoint

With the assistant in place, openloops is feature-complete. Reload, build your intent map, add your Anthropic key, and try the suggested prompts. Ask what to close this week and the assistant should name specific threads and reason about which are easy wins versus which need a real decision. Click into a single thread and ask how to finish it, and the answer should narrow to that thread's specifics.

The conversation reflects your real, current threads, and nothing about it leaves your machine except the thread summaries you can see in the grounding context itself.

The build is done. The final section steps back to look at what you've made: how it compares to the one mainstream attempt at this idea, what the privacy model adds up to, and where you might take it next.

What You've Built, and Where to Take It

You've built a complete system: browsing history flows in through capture, gets cleaned and segmented into sessions, clustered and scored into intent threads, optionally labeled and grounded by AI, and surfaced through a dashboard with a conversational assistant. Every stage runs on your own machine, and the AI layers are optional additions on top of a pipeline that works without them.

If the clustering reminds you of Chrome's old Journeys feature, that's a fair connection. Grouping history by topic instead of by time is the same starting point.

openloops takes it further: every thread carries a confidence score and a status, the AI layer adds labels and a concrete next step, the assistant reasons across threads on demand, and the whole thing is open source and local-first. This means that you can read and change exactly what it does with your data.

What the Privacy Model Adds Up To

Privacy shaped the build at every step, and it's worth collecting what that amounted to in one place. The entire core pipeline, capture through scored threads, runs locally in IndexedDB with no network calls of any kind. Your browsing history – the raw events, the sessions, the threads – never leaves your machine for the parts of the system that work without a key.

The two AI layers are the only paths by which any data leaves the device, and both are opt-in, gated on you providing your own API key. When they run, what they send is deliberately minimal: brand enrichment sends only bare domain names to context.dev, never URLs or page contents, and stripped of any local addresses first. Labeling and the assistant send thread titles, summaries, keywords, and sample page titles to Anthropic, the grounding context you can read directly in the code, and nothing more. Keys themselves live in chrome.storage.local, which never syncs.

Where to Take it Next

The build leaves a few deliberate simplifications that make good exercises.

The most satisfying one builds directly on code you've already written. The domain side has ambient.ts, which drops domains that appear on most of your active days. But the keyword side has no equivalent, so a word that's ubiquitous for you (say typescript, if you're a TypeScript developer) survives in every session's keywords and can nudge unrelated threads together.

The fix is a frequency-based keyword detector that mirrors detectAmbientDomains almost line for line, counting days-per-keyword instead of days-per-domain:

export function detectAmbientKeywords(sessions: Session[]): Set<string> {
  const allEvents = sessions.flatMap((s) => s.events);
  const activeDays = new Set(allEvents.map((e) => new Date(e.visitedAt).toDateString()));
  const totalActiveDays = activeDays.size;
  if (totalActiveDays < MIN_ACTIVE_DAYS) return new Set();

  const keywordDayMap = new Map<string, Set<string>>();
  for (const session of sessions) {
    const day = new Date(session.startedAt).toDateString();
    for (const kw of session.keywords) {
      if (!keywordDayMap.has(kw)) keywordDayMap.set(kw, new Set());
      keywordDayMap.get(kw)!.add(day);
    }
  }

  const ambient = new Set<string>();
  for (const [kw, days] of keywordDayMap) {
    if (days.size / totalActiveDays >= UBIQUITY_THRESHOLD) ambient.add(kw);
  }
  return ambient;
}

You'd then strip these keywords inside similarity exactly as ambient domains are stripped today, filtering them out of both sessionKeywords and the thread's keywordSet before the Jaccard call.

Two smaller exercises round it out. The session gap, similarity threshold, and ambient ubiquity threshold are all hardcoded constants. Lifting them into a settings panel backed by chrome.storage.local (the same store the API keys already use) would let you tune clustering to your own browsing.

And extractDomain strips only a leading www., so news.bbc.co.uk and bbc.co.uk are treated as different domains. Swapping its hostname logic for a library that uses the Public Suffix List (the canonical list of domain suffixes like .co.uk that browsers use to know where a registrable domain actually ends) would collapse subdomains of the same site correctly.

Since the whole pipeline is local and inspectable, each of these is straightforward to try against your own real data and see the effect immediately.

Wrapping up

openloops turns the flat, chronological record your browser keeps into a map of what you were actually trying to do, and helps you close the loops you left open.

The engineering underneath – time-gap segmentation, weighted Jaccard clustering with ambient-domain correction, heuristic scoring, AI labeling grounded in real company data, and a conversational layer over the result – is the kind of layered system where each stage is simple on its own and the value comes from how they compose.

Resources

Source Code

• The complete source is available on GitHub under the MIT license, so you can run it, read it, and reshape it to fit how you browse. If it helped you, consider giving it a star.

Core Documentation

• Chrome Extensions: Manifest V3: the extension platform openloops is built on

• chrome.history API: the search and getVisits methods the backfill relies on

• chrome.tabs API: onUpdated for live capture and create for Resume

• chrome.storage API: where API keys and preferences live, locally

• Anthropic API reference: the Messages endpoint used for labeling and the assistant

Services used

• Anthropic Console: create the API key for AI labeling and the assistant

• context.dev documentation: the brand-intelligence API used for grounding

• IndexedDB (MDN): the local database every pipeline stage reads and writes

Build tooling

• Vite: the build tool and dev server

• CRXJS Vite plugin: compiles a Manifest V3 extension with hot reloading

• idb: the typed, promise-based IndexedDB wrapper

• react-markdown: renders the assistant's Markdown replies

Debugging tools

• Chrome extension service worker DevTools: inspect live-capture logs and the pipeline console.table output

• The Application → IndexedDB panel in Chrome DevTools: browse raw_events, sessions, intent_threads, and domain_brands directly to verify each stage

Further reading

• Jaccard index: the set-similarity measure behind thread clustering

• Public Suffix List: the proper way to extract registrable domains, referenced as a future improvement

If this tutorial was useful, feel free to share it with others who might benefit. I'd really appreciate your thoughts, you can mention me on X at @wani_shola or connect with me on LinkedIn.

Millions of developers have published extensions to the Chrome Web Store, and building one is more approachable than you might think.

In this handbook you'll go from zero to a published Chrome extension using TypeScript, React, and Plasmo, a modern framework that handles the repetitive setup and configuration so you can focus on writing features instead of boilerplate.

Along the way you'll touch the real Chrome extension APIs that power production extensions: querying tabs, creating tab groups, and passing messages between different parts of an extension.

By the end you'll have working code, a mental model of how extensions are structured, and everything you need to publish your own ideas to the Chrome Web Store.

Table of Contents

• What is Plasmo?

• What You Will Build

• What You Will Learn

• Prerequisites

• Project Setup

• Understanding the Background Script

• Building the Popup UI

• Testing Your Extension

• Next Steps and Extension Ideas

• Deploying to Chrome Web Store

What is Plasmo?

Plasmo is an open-source framework for building browser extensions. Think of it as the equivalent of Create React App or Next.js, but for Chrome extensions.

Without Plasmo, building a Chrome extension requires manually writing a manifest.json file, wiring up build tooling, and configuring TypeScript and React yourself. Plasmo handles all of that.

A single command scaffolds a working project with TypeScript and React already configured. It reads your package.json and generates the manifest.json Chrome requires, so you never edit it directly.

Moreover, changes to your source files automatically rebuild and reload the extension in Chrome during development, and full type safety including types for Chrome's own APIs is available out of the box.

Plasmo doesn't hide the Chrome extension concepts from you. You still use chrome.tabs, chrome.runtime, and the rest of the Chrome APIs directly. It just removes the tedious scaffolding so you can start building immediately.

What You Will Build

In this tutorial, you'll build a Tab Grouper Chrome extension from scratch.

This extension automatically organizes your browser tabs by grouping them based on their website domain.

Example Use Case

Imagine you have 20 tabs open: 5 from GitHub, 4 from YouTube, 3 from Stack Overflow, and 8 from other websites.

With one click, the Tab Grouper extension will automatically create colored groups for each website, making it straightforward to find and manage your tabs.

What You Will Learn

By completing this tutorial, you'll get hands-on experience in three areas.

First, Chrome Extension Basics: how extensions work under the hood, the anatomy of an extension (manifest, background scripts, popups), and how to load and test extensions in Chrome during development.

Second, Chrome APIs: specifically chrome.tabs for managing browser tabs, chrome.tabGroups for creating and customizing tab groups, and chrome.runtime for passing messages between different parts of your extension.

Third, Modern Web Development tooling: TypeScript for type-safe JavaScript, React for building the popup UI, and the Plasmo framework that ties it all together.

Prerequisites

You don't need to be an expert in any of these, but you'll have the smoothest experience if you're comfortable with basic JavaScript or TypeScript and have a general understanding of HTML and CSS.

Some familiarity with React is helpful but not required. The pop-up component we'll build is simple enough to follow even if you're new to it.

On the software side, you'll need Node.js version 18 or higher (download here), Google Chrome, a code editor (VS Code is recommended), and pnpm as your package manager.

Verify Your Setup

Open your terminal and run these commands to confirm everything is installed:

node --version
# Should output v18.0.0 or higher

npm --version
# Should output 9.0.0 or higher

Getting Help

If you get stuck, review the complete code in the repository, consult the Chrome Extension documentation, or ask for help in the community forums.

Ready to Begin?

In the next section, you'll set up your development environment and create your first Chrome extension project.

Let's get started!

Project Setup

In this section, you'll use Plasmo to scaffold your Chrome extension project, then customize it for the Tab Grouper.

Rather than creating files manually, you'll let Plasmo generate a starter project with all required configuration, then explore what was created before customizing it for our needs.

Step 1: Install pnpm (Recommended)

Plasmo officially recommends pnpm for faster installs and better disk space usage. Check if you already have it:

pnpm --version

If you see a version number, skip to Step 2.

If you get "command not found", install it with:

npm install -g pnpm

Step 2: Create Your Extension Project

Run this command to create a new Plasmo project:

pnpm create plasmo tab-grouper

You'll see:

🟣 Creating a new Plasmo extension
📁 Project name: tab-grouper
? Extension description: (Give your extension a nice description)
? Author name: (Your Name)

Plasmo will then scaffold the project and install dependencies automatically. You might be prompted to enter a description and author name.

Fill these in however you like.

Step 3: Navigate to Your Project

cd tab-grouper

Step 4: Explore What Was Created

List the files that Plasmo generated:

ls -la

You should see something like this:

tab-grouper/
├── .git/                 # Git repository (already initialized!)
├── .github/              # GitHub Actions workflows
├── assets/
│   └── icon.png          # Default Plasmo icon 
├── node_modules/         # Dependencies (already installed!)
├── package.json          # Project configuration
├── popup.tsx             # Default popup 
├── .prettierrc.cjs       # Code formatting rules
├── .gitignore            # Git ignore rules
├── README.md             # Default readme
└── tsconfig.json         # TypeScript configuration

The key files to know about:

• assets/icon.png: The extension icon required by Chrome.

• package.json: Lists dependencies and scripts, and is where you configure the extension manifest.

• popup.tsx: The UI that appears when you click the extension icon.

• tsconfig.json: Contains TypeScript settings that are already correctly configured.

Step 5: Test the Default Extension

Make sure everything works before you customize it.

You can do this by starting the development server:

pnpm dev

You should see output like this:

🟣 Plasmo v0.90.5
🔴 The Browser Extension Framework
🔵 INFO   | Starting the extension development server...
🔵 INFO   | Building for target: chrome-mv3
🔵 INFO   | Loaded environment variables from: []
🟢 DONE   | Extension re-packaged in 1842ms! 🚀

View Extension:
📦 build/chrome-mv3-dev

Your extension is ready. Keep this terminal window open.

Plasmo watches for file changes and rebuilds automatically.

Step 6: Load the Extension in Chrome

Now load the extension into Chrome to test it:

1. Open Google Chrome

2. Go to chrome://extensions/

3. Enable Developer mode (toggle in top-right)

4. Click "Load unpacked"

5. Navigate to your project folder

6. Select the build/chrome-mv3-dev folder

7. Click "Select Folder"

Your extension should now appear in the list.

Step 7: Test the Default Popup

1. Click the puzzle piece icon in Chrome's toolbar

2. Find "tab-grouper" and pin it

3. Click the extension icon

You will see a default popup that says "Welcome to Plasmo!"

The extension is working. Now you can customize it.

Step 8: Update Extension Information

Open package.json in your editor. This file stores metadata about your project. name, version, description, dependencies, and scripts for building and running your extension.

Find these lines near the top:

{
  "name": "tab-grouper",
  "displayName": "tab-grouper",
  "version": "0.0.0",
  "description": "A basic Plasmo extension.",

Change them to:

{
  "name": "tab-grouper",
  "displayName": "Tab Grouper",
  "version": "1.0.0",
  "description": "A simple Chrome extension - group tabs by domain",

Save the file.

Step 9: Add Required Permissions (Critical!)

This is a critical step. Without permissions, your extension will fail with errors like:

TypeError: Cannot read properties of undefined (reading 'query')

Chrome extensions must declare which browser APIs they intend to use. In package.json, find the "manifest" section.

It looks like this:

"manifest": {
  "host_permissions": [
    "https://*/*"
  ]
}

Replace it with:

"manifest": {
  "permissions": [
    "tabs",
    "tabGroups"
  ]
}

Save the file. The tabs permission allows you to read tab information (required for chrome.tabs.query()), and tabGroups allows you to create and manage tab groups (required for chrome.tabGroups.update()).

Finding the right permissions for your own extensions:

The Chrome Extension Permissions Reference lists every available permission and what it unlocks.

Each API's documentation page also lists which permissions it requires, for example, the chrome.tabs API page specifies the "tabs" permission.

If you're using Plasmo, the Manifest Configuration docs explain how to add permissions through package.json.

As a general rule: if you're getting undefined errors when calling a Chrome API, a missing permission is the first thing to check.

Step 10: Verify Hot Reload Works

Plasmo automatically reloads your extension when you save changes.

Check the terminal where pnpm dev is running. After saving package.json you should see something like:

🔄 Reloading extension...
✅ Ready in 0.8s

Your project is now ready: a working extension loaded in Chrome, a development server running with hot reload, and the required permissions in place.

Leave the dev server running and the extension loaded as you work through the next sections. Your changes will reload automatically.

Section Summary

In this section you installed pnpm, scaffolded a new extension with pnpm create plasmo, explored the generated project structure, started the development server, loaded the extension in Chrome, and updated the extension metadata and permissions.

Next: You'll create the background script that handles the tab grouping logic.

Understanding the Background Script

The background script is the heart of your extension. It runs persistently behind the scenes and contains the core logic.

In this case, the code that groups your tabs by domain.

What is a Background Script?

A background script runs continuously even when the popup is closed.

It can listen to browser events like tabs opening, closing, or updating, perform tasks that don't require direct user interaction, and communicate with other parts of the extension by passing messages.

Think of it as the server-side of your extension. The popup is just a UI that talks to it.

Step 1: Create background.ts

Plasmo's scaffolding didn't create a background script by default, so you'll create this file from scratch. Create a new file called background.ts in your project root (the same level as popup.tsx):

export {}

// Background script - runs in the background and handles tab grouping logic

console.log("Tab Grouper background script loaded!")

// Listen for messages from the popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

The export {} at the top is required by Plasmo to treat this file as a module. Without it you may get errors about conflicting global variable declarations.

The console.log will help you verify the script loaded correctly (you'll see it in the extension's DevTools console). chrome.runtime.onMessage sets up a listener so the background script can receive instructions from the popup.

When it receives a "GROUP_TABS" message, it calls the grouping function.

You can read more about this messaging pattern in the Chrome Extensions documentation.

Step 2: Implement Tab Grouping Logic

Now add the main grouping function below the message listener:

async function groupTabsByDomain() {
  try {
    // Step 1: Get all tabs in the current window
    const tabs = await chrome.tabs.query({ currentWindow: true })

    // Step 2: Create a Map to organize tabs by domain
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    // Step 3: Loop through each tab and group by domain
    tabs.forEach(tab => {
      // Skip tabs without URLs
      if (!tab.url) return

      // Extract the domain from the URL
      const domain = getDomainFromUrl(tab.url)

      // Skip invalid domains (like chrome:// pages)
      if (!domain) return

      // Add tab to the appropriate domain group
      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    // Step 4: Create tab groups for each domain (only if 2+ tabs)
    for (const [domain, domainTabs] of domainGroups) {
      // Skip domains with only 1 tab
      if (domainTabs.length < 2) continue

      // Get all tab IDs
      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      // Create the tab group
      const groupId = await chrome.tabs.group({ tabIds })

      // Customize the group with a title and color
      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain) // Randomized Tab Group colors.
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

The function starts by querying all tabs in the current window, then iterates over them to build a Map keyed by domain name.

Once every tab has been sorted into a domain bucket, it loops through the map and calls chrome.tabs.group() for any domain that has two or more tabs, then immediately customizes the resulting group with a title and color.

Domains with only a single tab are skipped. There's no point grouping a lone tab.

Step 3: Extract Domain Helper

Add a helper function to pull the hostname out of a URL:

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)

    // Skip Chrome internal pages (chrome://, chrome-extension://)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }

    // Remove "www." prefix and return the hostname
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    // Return null if URL is invalid
    return null
  }
}

new URL(url) gives us a structured object to work with rather than string-parsing the URL manually.

The protocol check filters out Chrome's internal pages like chrome://extensions and chrome://settings, which extensions can't access.

The .replace(/^www\./, "") ensures that www.github.com and github.com are treated as the same domain rather than two separate groups.

The whole thing is wrapped in a try-catch so malformed URLs simply return null and get skipped.

In practice: https://www.github.com/user/repo becomes github.com, https://youtube.com/watch?v=123 becomes youtube.com, and chrome://extensions returns null.

Step 4: Color Assignment Helper

Add a function to deterministically assign a color to each domain:

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  // Available colors in Chrome
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  // Create a simple hash from the domain name
  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  // Return a color based on the hash
  return colors[Math.abs(hash) % colors.length]
}

Chrome supports eight colors for tab groups. Rather than assigning them randomly (which would change every time you group), this function hashes the domain name to a number and uses the modulo operator to pick a consistent index into the color array.

The result is that github.com always gets the same color across sessions, while different domains are likely to get different colors.

Complete background.ts File

Your complete background.ts should look like this:

export {}

console.log("Tab Grouper background script loaded!")

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

async function groupTabsByDomain() {
  try {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    tabs.forEach(tab => {
      if (!tab.url) return
      const domain = getDomainFromUrl(tab.url)
      if (!domain) return

      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    for (const [domain, domainTabs] of domainGroups) {
      if (domainTabs.length < 2) continue

      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      const groupId = await chrome.tabs.group({ tabIds })

      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain)
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    return null
  }
}

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  return colors[Math.abs(hash) % colors.length]
}

Testing the Background Script

If your development server isn't already running from the previous section, start it:

pnpm dev

To verify the background script loaded correctly, go to chrome://extensions, find "Tab Grouper Tutorial", and click the "service worker" link.

A DevTools console will open and you should see "Tab Grouper background script loaded!" confirming everything is wired up.

Building the Popup UI

The popup is the small window that appears when a user clicks your extension icon in the Chrome toolbar.

It can display information, provide buttons for actions, and show settings.

In this section you'll build a React-based popup that shows live tab statistics and triggers the grouping logic in the background script.

Step 1: Replace popup.tsx

When you ran pnpm create plasmo, a default popup.tsx was created that just displays a welcome message.

Open that file and replace all of its contents with this starting skeleton:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  return (
    <div>
      <h2>Tab Grouper</h2>
      <button>Group Tabs</button>
    </div>
  )
}

export default IndexPopup

Save the file and the extension will automatically reload.

The three state variables track the number of open tabs, the number of existing groups, and whether a grouping operation is currently in progress.

That last one lets us disable the button and show a loading state so users can't trigger multiple groupings at once.

Step 2: Load Statistics

Now add the logic to load tab and group counts when the popup opens. Add this inside the IndexPopup function, right after the state declarations:

// Load tab statistics when popup opens
useEffect(() => {
  loadStats()
}, [])

async function loadStats() {
  const tabs = await chrome.tabs.query({ currentWindow: true })
  const groups = await chrome.tabGroups.query({
    windowId: chrome.windows.WINDOW_ID_CURRENT
  })

  setTabCount(tabs.length)
  setGroupCount(groups.length)
}

The useEffect with an empty dependency array [] runs once when the component first mounts. In other words, every time the popup opens.

It calls loadStats, which queries Chrome for the current window's tabs and groups, then updates the state variables with the counts.

Step 3: Trigger Tab Grouping

Add the handler that sends a message to the background script when the button is clicked:

async function handleGroupTabs() {
  setIsGrouping(true)

  // Send message to background script
  await chrome.runtime.sendMessage({ type: "GROUP_TABS" })

  // Refresh statistics
  await loadStats()
  setIsGrouping(false)
}

chrome.runtime.sendMessage delivers the { type: "GROUP_TABS" } message to the listener we set up in background.ts.

After the background script finishes, we reload the statistics so the group count updates immediately, then re-enable the button.

Step 4: Build the UI

Replace the placeholder return statement with this complete, styled version:

return (
  <div style={{
    width: 300,
    padding: 20,
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
  }}>
    {/* Header */}
    <div style={{ marginBottom: 20 }}>
      <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
        🗂️ Tab Grouper
      </h2>
      <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
        Organize your tabs by domain
      </p>
    </div>

    {/* Statistics */}
    <div style={{
      display: "flex",
      gap: 12,
      marginBottom: 20,
      padding: 12,
      background: "#f5f5f5",
      borderRadius: 8
    }}>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
          {tabCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Open Tabs
        </div>
      </div>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
          {groupCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Tab Groups
        </div>
      </div>
    </div>

    {/* Group Button */}
    <button
      onClick={handleGroupTabs}
      disabled={isGrouping}
      style={{
        width: "100%",
        padding: "12px 16px",
        fontSize: 14,
        fontWeight: 500,
        color: "white",
        background: isGrouping ? "#ccc" : "#0066ff",
        border: "none",
        borderRadius: 8,
        cursor: isGrouping ? "not-allowed" : "pointer",
        transition: "background 0.2s"
      }}
    >
      {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
    </button>

    {/* Footer */}
    <div style={{
      marginTop: 16,
      padding: 12,
      fontSize: 12,
      color: "#666",
      background: "#fff9e6",
      borderRadius: 6,
      border: "1px solid #ffe066"
    }}>
      💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
    </div>
  </div>
)

The UI has four parts: a header with the extension title and a short description, a statistics box showing the live tab and group counts side by side, the main action button (which grays out and changes text to "Grouping..." while work is in progress), and a tip box at the bottom.

This tutorial uses inline styles for simplicity. In a production extension, you'd likely reach for CSS modules, Tailwind, or styled-components instead.

Complete popup.tsx File

Your complete popup.tsx should look like this:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  useEffect(() => {
    loadStats()
  }, [])

  async function loadStats() {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const groups = await chrome.tabGroups.query({
      windowId: chrome.windows.WINDOW_ID_CURRENT
    })

    setTabCount(tabs.length)
    setGroupCount(groups.length)
  }

  async function handleGroupTabs() {
    setIsGrouping(true)
    await chrome.runtime.sendMessage({ type: "GROUP_TABS" })
    await loadStats()
    setIsGrouping(false)
  }

  return (
    <div style={{
      width: 300,
      padding: 20,
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
    }}>
      <div style={{ marginBottom: 20 }}>
        <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
          🗂️ Tab Grouper
        </h2>
        <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
          Organize your tabs by domain
        </p>
      </div>

      <div style={{
        display: "flex",
        gap: 12,
        marginBottom: 20,
        padding: 12,
        background: "#f5f5f5",
        borderRadius: 8
      }}>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
            {tabCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Open Tabs
          </div>
        </div>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
            {groupCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Tab Groups
          </div>
        </div>
      </div>

      <button
        onClick={handleGroupTabs}
        disabled={isGrouping}
        style={{
          width: "100%",
          padding: "12px 16px",
          fontSize: 14,
          fontWeight: 500,
          color: "white",
          background: isGrouping ? "#ccc" : "#0066ff",
          border: "none",
          borderRadius: 8,
          cursor: isGrouping ? "not-allowed" : "pointer",
          transition: "background 0.2s"
        }}
      >
        {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
      </button>

      <div style={{
        marginTop: 16,
        padding: 12,
        fontSize: 12,
        color: "#666",
        background: "#fff9e6",
        borderRadius: 6,
        border: "1px solid #ffe066"
      }}>
        💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
      </div>
    </div>
  )
}

export default IndexPopup

Testing Your Extension

Now that you have both the background script and popup UI built, it's time to verify that everything works together in Chrome.

Step 1: Make Sure the Dev Server is Running

If pnpm dev isn't already running from an earlier step, start it now:

pnpm run dev # or pnpm dev

Plasmo will build the extension into build/chrome-mv3-dev and watch for changes.

Step 2: Load the Extension in Chrome

If you haven't already loaded the extension, go to chrome://extensions/, enable Developer mode, click Load unpacked, and select the build/chrome-mv3-dev folder.

Once loaded you should see the extension listed with the name "Tab Grouper Tutorial", version "1.0.0", and status Enabled.

Step 3: Pin the Extension

Click the puzzle piece icon in the Chrome toolbar, find "Tab Grouper Tutorial", and click the pin icon to keep it visible.

The extension icon will now appear directly in your toolbar.

Step 4: Test the Extension

Test 1: Open Multiple Tabs

Open several tabs across a few domains so there's something to group:

1. https://github.com/topics, https://github.com/trending, https://github.com/explore

2. https://www.youtube.com/ and https://www.youtube.com/trending

3. https://stackoverflow.com/questions and https://stackoverflow.com/tags

Have at least 7 tabs open.

Test 2: Group the Tabs

Click the Tab Grouper extension icon. The popup should appear showing your open tab count (7 or more) and group count (probably 0).

Click "Group Tabs by Domain" and watch your tabs get organized into colored groups.

Test 3: Verify Groups

After clicking the button, GitHub tabs should be grouped together with a label like "github.com" and a consistent color, and YouTube tabs similarly.

Click the extension icon again, the group count should now show 2, while the tab count stays the same.

Step 5: Debug the Extension

If something doesn't work, Chrome's DevTools are your best friend.

To inspect the background script, go to chrome://extensions/, find your extension, and click the "service worker" link.

A DevTools console opens where you can look for the "Tab Grouper background script loaded!" message and any error output in red.

To inspect the popup, right-click the extension icon and select "Inspect popup". This opens DevTools for the popup specifically — check the Console tab for any errors there.

If nothing happens when you click the button, check the background script console for errors, confirm you have at least 2 tabs from the same domain, and verify the message is being sent (look in the popup console for any sendMessage failures).

If tabs aren't grouping, double-check that you added the tabs and tabGroups permissions to package.json and reloaded the extension after saving.

If you see "Extension cannot access chrome://...", that's expected behavior — extensions can't interact with Chrome's internal pages and the code skips them intentionally.

Step 6: Hot Reloading

One of the benefits of Plasmo is hot reloading, which allows you to update code in a running app instantly without needing to restart it manually.

Open popup.tsx, change the header emoji from 🗂️ to 📁, and save.

The extension reloads automatically.

Click the icon and you'll see the updated emoji immediately.

Hot reloading is advantageous because it speeds up development by letting you see changes in real time.

You can change the emoji back afterward if you'd like to keep the extension consistent with the rest of the tutorial examples and screenshots.

Step 7: Test Edge Cases

It's worth testing a few scenarios to make sure the extension handles them gracefully.

If you close all tabs except one and click "Group Tabs", nothing should happen. The extension requires at least two tabs from the same domain to form a group. Opening chrome://extensions and chrome://settings and then grouping should also do nothing, since those pages are filtered out.

If you have one tab from reddit.com and one from freecodecamp.org, each domain appearing only once, no groups should be created.

Step 8: Production Build

When you're ready to share your extension, run:

pnpm run build

This creates a production-optimized version in build/chrome-mv3-prod, minified JavaScript, no development-only code, and smaller file size.

To verify the production build, go to chrome://extensions/, remove the development version, click "Load unpacked", and select build/chrome-mv3-prod. Test thoroughly before publishing.

The extension is lightweight (under 100 KB), only runs when you click the button, and has no background processes when idle.

Next Steps and Extension Ideas

Congratulations on building your first Chrome extension!

You now have a working tool that groups tabs by domain with one click, shows live statistics about open tabs and groups, and is built on modern tooling: TypeScript, React, and Plasmo following Chrome extension best practices.

The extension is a solid foundation. Here are some ideas for where to take it next.

1. Auto-Grouping

Instead of requiring a button click, you could automatically group new tabs as they're opened. You'd listen for the chrome.tabs.onCreated event in background.ts and trigger groupTabsByDomain() with a short delay to let the page URL load:

// In background.ts
chrome.tabs.onCreated.addListener(async (tab) => {
  // Wait a bit for the URL to load
  setTimeout(() => {
    groupTabsByDomain()
  }, 2000)
})

This gets into event listeners, asynchronous timing, and thinking carefully about when to fire — a good next step for understanding how background scripts can be more proactive.

2. Keyboard Shortcuts

You can trigger grouping without even opening the popup by adding a keyboard shortcut. Add a commands section to the manifest in package.json:

"manifest": {
  "commands": {
    "group-tabs": {
      "suggested_key": {
        "default": "Ctrl+Shift+G",
        "mac": "Command+Shift+G"
      },
      "description": "Group tabs by domain"
    }
  }
}

Then listen for the command in background.ts:

chrome.commands.onCommand.addListener((command) => {
  if (command === "group-tabs") {
    groupTabsByDomain()
  }
})

3. Category-Based Grouping

Rather than grouping by raw domain, you could group by category — putting GitHub, Stack Overflow, and npm together in a "Dev" group, for instance:

const categories = {
  social: ["facebook.com", "twitter.com", "instagram.com"],
  shopping: ["amazon.com", "ebay.com", "etsy.com"],
  dev: ["github.com", "stackoverflow.com", "npmjs.com"]
}

function getCategoryForDomain(domain: string): string {
  for (const [category, domains] of Object.entries(categories)) {
    if (domains.includes(domain)) {
      return category
    }
  }
  return "other"
}

4. Options Page

Plasmo makes it trivial to add a settings page by creating an options.tsx file.

This is where you'd let users toggle auto-grouping, choose between domain and category mode, or configure their own category mappings.

It's a good introduction to the Chrome Storage API and persisting user preferences.

function OptionsPage() {
  return (
    <div>
      <h1>Tab Grouper Settings</h1>
      <label>
        <input type="checkbox" />
        Enable auto-grouping
      </label>
      <label>
        <input type="checkbox" />
        Group by category instead of domain
      </label>
    </div>
  )
}

5. Tab Age Tracking

You could track when each tab was created and surface tabs that have been sitting untouched for a week or more, a nice way to encourage tab hygiene:

// Track tab creation times
const tabCreationTimes = new Map<number, number>()

chrome.tabs.onCreated.addListener((tab) => {
  if (tab.id) {
    tabCreationTimes.set(tab.id, Date.now())
  }
})

// Find old tabs (e.g., > 7 days)
function getOldTabs(): chrome.tabs.Tab[] {
  const sevenDaysAgo = Date.now() - (7 * 24 * 60 * 60 * 1000)
  return tabs.filter(tab => {
    const created = tabCreationTimes.get(tab.id!)
    return created && created < sevenDaysAgo
  })
}

6. Search Within Groups

A search bar in the popup would let users filter their open tabs by title, making it easy to jump to a specific tab:

const [searchQuery, setSearchQuery] = useState("")

const filteredTabs = tabs.filter(tab =>
  tab.title?.toLowerCase().includes(searchQuery.toLowerCase())
)

7. Export/Import Groups

You could let users save their current tab groups to a JSON file and restore them later. Useful for preserving a working session across restarts:

// Export
async function exportGroups() {
  const groups = await chrome.tabGroups.query({})
  const data = JSON.stringify(groups)
  const blob = new Blob([data], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  chrome.downloads.download({ url, filename: 'tab-groups.json' })
}

// Import
async function importGroups(file: File) {
  const text = await file.text()
  const groups = JSON.parse(text)
  // Restore groups...
}

8. Group Statistics Dashboard

An expanded popup could show browsing analytics, total tabs opened today, most-visited domain, and more:

function Statistics() {
  const [stats, setStats] = useState({
    totalTabs: 0,
    totalGroups: 0,
    mostUsedDomain: "",
    tabsToday: 0
  })

  return (
    <div>
      <h3>Browsing Statistics</h3>
      <p>Total tabs opened today: {stats.tabsToday}</p>
      <p>Most visited domain: {stats.mostUsedDomain}</p>
    </div>
  )
}

Learning Resources

If you want to go deeper, the official Chrome Extension docs are excellent and cover every API in detail.

The Chrome Extension Samples repository on GitHub has dozens of real examples to learn from. For Plasmo-specific questions, the Plasmo documentation and example repository are the best starting points, and the community is active on Plasmo Discord.

The React docs and TypeScript docs are worth bookmarking as reference material, and the React TypeScript Cheatsheet is handy when you're unsure about specific type patterns.

For community support, Stack Overflow's chrome-extension tag is well-monitored, and r/chrome_extensions on Reddit is a friendly place to ask questions.

Deploying to Chrome Web Store

Now that you've built and tested your extension, here's how to publish it and share it with the world.

What You'll Need

Before you can publish, you'll need a completed and tested extension, a Google account, a $5 USD one-time developer registration fee, and some store assets such as icons, screenshots, and a written description.

The $5 fee is a one-time charge (not annual) that Google uses to verify developer identity and reduce spam. It covers unlimited extension submissions and is processed immediately via Google Payments.

Step 1: Create a Production Build

Build your extension for production if you didn't do this before:

cd tab-grouper-tutorial
npm run build

This creates an optimized version in build/chrome-mv3-prod/. The production build minifies JavaScript and CSS for a smaller file size, strips out development-only code and console logs, and optimizes assets for faster loading.

Before uploading, load build/chrome-mv3-prod/ as an unpacked extension and test all features one more time to confirm nothing broke in the build process.

Step 2: Create Store Assets

Extension Icons

You'll need icons in three sizes: 128×128 pixels for the main store listing (required), 48×48 for the extension management page, and 16×16 for use as a favicon.

All should be PNG files with transparent backgrounds. Keep the design simple and recognizable at small sizes. Avoid putting text in the 16×16 version.

Figma is free and works well for this, as does Canva or GIMP.

Screenshots

Upload between 1 and 5 screenshots at either 1280×800 or 640×400 pixels (PNG or JPEG).

Show the extension in actual use rather than mockups. The popup with statistics, tabs being grouped, and the before/after state all work well.

Adding annotations to highlight key features helps users understand what they're looking at.

Promotional Images (Optional)

If you want to be featured on the store, you can also upload a small tile (440×280), large tile (920×680), and marquee image (1400×560). These are only needed if Google chooses to promote your extension.

Demo Video (Optional)

A short YouTube video (30–60 seconds) showing the extension in action can significantly increase conversions. Link to it in your store listing.

Step 3: Write Your Store Listing

Extension Name (45 character limit): Be clear and descriptive. "Tab Grouper - Organize Tabs by Domain" works well. Avoid keyword stuffing or excessive punctuation.

Summary (132 character limit): This is what appears in search results. Lead with what the extension does: "Automatically organize browser tabs by domain. One-click grouping keeps your workspace clean and productive."

Detailed Description (16,000 character limit): Start with what the extension does, list features clearly, explain how to use it, address privacy, and provide contact information. Here's a template you can adapt:

## What is Tab Grouper?

Tab Grouper automatically organizes your browser tabs by grouping them based on their website domain. No more hunting through dozens of tabs - everything is neatly organized.

## Features

- ✅ One-click tab grouping
- ✅ Automatic color-coding by domain
- ✅ Real-time statistics
- ✅ Works with all websites
- ✅ Lightweight and fast

## How to Use

1. Click the Tab Grouper icon in your toolbar
2. Click "Group Tabs by Domain"
3. Your tabs are instantly organized

## Why You Need This

If you regularly have numerous tabs open, finding the right one can waste valuable time. Tab Grouper solves this by automatically organizing tabs into colored groups, making navigation quick and straightforward.

## Privacy

This extension does not collect any personal data. It only accesses tab information locally to perform grouping. No data is sent to external servers.

## Support

Found a bug or have a suggestion? Contact us at support@example.com

Category: Choose Productivity for Tab Grouper. You can add additional languages later if you want to localize the listing.

Step 4: Register as a Chrome Web Store Developer

Go to the Chrome Web Store Developer Dashboard, sign in with your Google account, accept the Developer Agreement, and pay the $5 registration fee. Your account is activated within minutes.

Step 5: Submit Your Extension

In the Developer Dashboard, click "New Item" and upload your extension. You can either manually zip the build/chrome-mv3-prod/ folder or use Plasmo's package command:

# Option 1: Manual zip
cd build/chrome-mv3-prod
zip -r ../../tab-grouper.zip .

# Option 2: Use Plasmo package command
cd tab-grouper-tutorial
npm run package

Once uploaded, fill in all four sections of the store listing form: Product details (name, summary, description, category, language), Graphic assets (icon and screenshots), Privacy practices (see below), and Distribution (visibility, regions, pricing).

Single Purpose Description

Chrome requires each extension to have a single, clearly stated purpose. For Tab Grouper: "This extension organizes browser tabs by grouping them based on their domain name, helping users manage multiple open tabs efficiently."

Permission Justification

You'll need to justify each permission you declared. For tabs: "The tabs permission is required to read tab URLs and titles in order to group them by domain." For tabGroups: "The tabGroups permission is required to create and manage tab groups for organization."

Privacy Policy

Even though Tab Grouper doesn't collect personal data, Chrome may require a privacy policy. Host one on GitHub Pages or your personal website and link to it. Here's a minimal template:

# Privacy Policy for Tab Grouper

## Data Collection
Tab Grouper does not collect, store, or transmit any personal data.

## Permissions
- **tabs**: Used only to read tab URLs for grouping purposes
- **tabGroups**: Used only to create and manage tab groups

## Local Processing
All tab grouping happens locally in your browser. No data is sent to external servers.

## Contact
For questions: your-email@example.com

Last updated: [Current Date]

Step 6: Submit for Review

Before clicking submit, run through this checklist:

• Production build tested thoroughly

• All store assets uploaded (icon + at least one screenshot)

• Description is clear and accurate

• Permissions are justified

• Privacy policy is linked

• Extension name is descriptive

When you're ready, click "Submit for review", confirm your details, and click "Publish". Your extension enters the review queue.

Step 7: The Review Process

Google typically reviews extensions within 1–3 business days for straightforward submissions, though complex extensions or first submissions can take up to a week. Reviewers check that the extension works as described, that permissions are justified, that there's no malicious code, and that the listing complies with Chrome Web Store policies.

You can track your status in the Developer Dashboard: Pending review → In review → Approved or Rejected. If rejected, Google will email you specific reasons and instructions for resubmitting.

The most common rejection reasons are insufficient permission justification, misleading descriptions, missing privacy policies, and requesting more permissions than necessary. Address each point in the rejection email, update your submission, and resubmit.

Step 8: After Approval

Once approved, your extension is live at https://chrome.google.com/webstore/detail/[extension-id]. Share the link on social media, write a blog post, post to Reddit (r/chrome, r/chrome_extensions), or submit to Product Hunt to drive installs.

The Developer Dashboard gives you ongoing analytics — total and weekly installs, reviews and ratings, impressions, and uninstall counts. Check it regularly, especially in the first week. Respond to reviews (particularly negative ones), thank users for positive feedback, and use reported bugs to prioritize future updates.

Step 9: Publishing Updates

When you fix bugs or add features, bump the version number in package.json (following Semantic Versioning — patch for bug fixes, minor for new features, major for breaking changes), run npm run build, and upload the new package through the Developer Dashboard's Package tab. Updates are typically reviewed faster than initial submissions, often within 24 hours.

Step 10: Managing Your Extension Long-Term

The Chrome Web Store provides built-in analytics, but you can also add Google Analytics if you need more detail.

For user support, an email address in the description or a GitHub issues page both work well. As you add features, keep the description updated and maintain a changelog so users know what changed and when. Responding to user questions and reviews goes a long way toward building a loyal base of users who'll recommend the extension to others.

Troubleshooting Common Publishing Issues

"Package is invalid" on upload: Make sure you zipped the contents of build/chrome-mv3-prod/ rather than the folder itself, and verify the generated manifest.json is valid JSON.

Rejection: Permissions Not Justified: In the "Permission justification" field, be specific about which feature requires each permission and what would break without it.

Rejection: Single Purpose Unclear: Rewrite the single purpose description to focus on one main function, stated plainly.

Low installation rate after launch: Poor screenshots are often the culprit — they're the first thing most users look at. Make sure they clearly show the extension solving a real problem. Building even a small number of early reviews also makes a big difference to new visitors.

Alternative Distribution

The Chrome Web Store is the right choice for most public extensions. If you're building an internal tool, an Unlisted extension (accessible only via direct link, not searchable) is a good option.

If you need to restrict it to users in a specific Google Workspace organization, a Private extension is available for that. Self-hosting and sideloading is possible but requires users to enable Developer Mode manually, so it's only practical for very technical audiences.

Congratulations!

You've gone from an empty folder to a live Chrome extension on the Web Store. Along the way you learned how extensions are structured, how background scripts and popups communicate, how Chrome's tab APIs work, and how to navigate the publishing process end to end.

More than any specific API or configuration detail, the most important thing you've built is a mental model for how extensions work and that transfers directly to any extension idea you want to build next.

Keep building, keep learning, and keep shipping!

Usually, you’d open DevTools or an SEO auditing tool to find answers to these questions. But what if you could analyze any web page instantly, without leaving your browser?

In this tutorial, you’ll learn how to build a Chrome extension that scans and analyzes any webpage for titles, meta descriptions, headings, and links.

By the end of this article, you’ll:

• Understand how Manifest V3 works in Chrome Extensions

• Learn how to inject content scripts into web pages

• Build a popup UI that fetches and displays structured data

• Explore how this same foundation can be extended with AI-powered insights

💡 This guide focuses on learning and education – no frameworks or build tools required. Just HTML, CSS, and vanilla JavaScript.

Table of Contents

• Prerequisites

• Step 1: Understanding How Chrome Extensions Work

• Step 2: Set Up the Project Structure

• Step 3: Define the Manifest File

• Step 4: Create the Popup UI

• Step 5: Write the Content Script (content.js)

• Step 6: Connect the Popup and Content Script

• Step 7: Load and Test Your Extension

• Step 8: Add Optional Enhancements

• Step 9: Publish to the Chrome Web Store

• Final Thoughts

🧰 Prerequisites

Before starting this tutorial, make sure you have:

• A basic understanding of HTML, CSS, and JavaScript

• A recent version of Google Chrome installed on your system

• Familiarity with using Chrome DevTools (optional but helpful)

• A code editor like VS Code or Sublime Text

• A local folder where you can create and organize your extension files

💡 Again, no frameworks or build tools are required. We’ll use only vanilla JavaScript and simple web technologies throughout this guide.

🧩 Step 1: Understanding How Chrome Extensions Work

A Chrome extension is just a bundle of web technologies – HTML, CSS, and JS – that extends browser functionality.

Extensions can have multiple parts:

• Manifest file (manifest.json): defines permissions, icons, and structure.

• Content scripts: run inside web pages and access the DOM.

• Background scripts: handle long-running or event-driven logic.

• Popup UI: what users see when they click your extension icon.

Here’s a high-level flow of what we’ll build:

[Popup UI] <—> [Content Script] <—> [Web Page DOM]

When the user clicks “Analyze,” the popup will send a message to the content script. The script will then read the DOM and send back results like page title, description, headings, and links.

🧠 Step 2: Set Up the Project Structure

Create a new folder called page-analyzer-extension. Inside it, create these files:

page-analyzer-extension/
│
├── manifest.json
├── popup.html
├── popup.js
├── content.js
├── styles.css
└── icons/
    ├── icon16.png
    ├── icon48.png
    └── icon128.png

Icons are optional, but they make the extension look professional. You can use placeholders or generate them from favicon.io.

⚙️ Step 3: Define the Manifest File

Create manifest.json and paste this in:

{
  "manifest_version": 3,
  "name": "Page Analyzer",
  "version": "1.0",
  "description": "Analyze any web page for its title, description, headings, and links.",
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ]
}

Let’s break this down:

• manifest_version: 3: the latest version with security and performance improvements

• permissions: allow the extension to access the active tab and run scripts

• content_scripts: define which JS files should automatically run in web pages

🧩 Step 4: Create the Popup UI

The popup appears when users click the extension icon.

popup.html:

<!DOCTYPE html>
<html>
  <head>
    <title>Page Analyzer</title>
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <h2>Page Analyzer</h2>
    <p>Click below to analyze the current page:</p>
    <button id="analyze">Analyze Page</button>
    <div id="results"></div>

    <script src="popup.js"></script>
  </body>
</html>

styles.css:

body {
  font-family: system-ui, sans-serif;
  padding: 12px;
  width: 280px;
}
button {
  background: #2563eb;
  color: white;
  border: none;
  padding: 8px 14px;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
}
#results {
  margin-top: 12px;
  font-size: 13px;
  line-height: 1.4;
  word-wrap: break-word;
}

🧠 Step 5: Write the Content Script (content.js)

This script will analyze the web page.

function analyzePage() {
  const title = document.title || "No title found";
  const description =
    document.querySelector('meta[name="description"]')?.content || "No description found";
  const headings = Array.from(document.querySelectorAll("h1, h2, h3")).map((h) =>
    h.innerText.trim()
  );
  const links = document.querySelectorAll("a").length;

  return {
    title,
    description,
    headings,
    linkCount: links,
    domain: location.hostname,
  };
}

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === "analyze") {
    sendResponse(analyzePage());
  }
});

What’s happening here:

• We extract the title, description, headings, and total link count

• We return this data as a structured object

• The script listens for messages from the popup and responds with the analysis

⚡ Step 6: Connect the Popup and Content Script

In popup.js, add the logic that triggers page analysis.

document.getElementById("analyze").addEventListener("click", async () => {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });

  chrome.tabs.sendMessage(tab.id, { action: "analyze" }, (response) => {
    const resultContainer = document.getElementById("results");

    if (!response) {
      resultContainer.innerText = "Unable to analyze this page.";
      return;
    }

    const { title, description, headings, linkCount, domain } = response;
    resultContainer.innerHTML = `
      <strong>Domain:</strong> ${domain}<br/>
      <strong>Title:</strong> ${title}<br/>
      <strong>Description:</strong> ${description}<br/>
      <strong>Headings:</strong> ${
        headings.length ? headings.join(", ") : "No headings found"
      }<br/>
      <strong>Links:</strong> ${linkCount}
    `;
  });
});

This uses the Chrome Tabs API to find the current tab and send a message to the content script. When the script responds, we update the popup with the results.

🧪 Step 7: Load and Test Your Extension

1. Open chrome://extensions/

2. Enable Developer Mode

3. Click Load Unpacked

4. Select your project folder

Now, pin your extension to the toolbar, open any website, and click “Analyze Page.”

You’ll instantly see:

• The page’s title

• Meta description

• Extracted headings (H1–H3)

• Link count

• Domain name

🎉 Congratulations! You’ve built a working web page analyzer.

🧩 Step 8: Add Optional Enhancements

Now that the basics work, here are some ways to level up your project.

🧠 1. Add AI Insights

You can connect to an AI API (like OpenAI or Gemini) to summarize the page or evaluate SEO structure.

// Example: pseudo-code for calling an AI API
const aiResponse = await fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [
      { role: "system", content: "You are an SEO assistant." },
      { role: "user", content: `Analyze the following page info: ${JSON.stringify(pageData)}` }
    ]
  })
});

For example, after building this basic analyzer, I expanded it into a full-featured RankingsFactor AI SEO Extension which combines this same foundation with:

• AI-generated keyword suggestions

• Metadata improvement recommendations

• Automatic screenshot capture

• Page freshness detection

This demonstrates how a simple developer project can evolve into a powerful, production-ready tool.

🔍 2. Detect Missing SEO Tags

You can check for missing tags like this:

const missingTags = [];
if (!document.querySelector('meta[name="description"]')) missingTags.push("description");
if (!document.querySelector('meta[property="og:title"]')) missingTags.push("og:title");

🖼️ 3. Add Screenshot or Report Export

Use the chrome.tabs.captureVisibleTab() API to take a screenshot, or generate a downloadable HTML/JSON report.

🧭 Step 9: Publish to the Chrome Web Store

Once you’ve tested your extension, visit chrome.google.com/webstore/devconsole. You’ll need to pay a one-time $5 developer registration fee, then you can upload your extension as a ZIP file. Make sure you write a clear, helpful description before submitting your extension for review.

✅ Final Thoughts

In this tutorial, you learned:

• How Chrome extensions communicate between scripts and web pages

• How to safely extract DOM data

• How to display structured information in a popup UI

• How to extend browser tools with AI for smarter analysis

Browser extensions are an incredible way to bring web automation, analysis, and creativity directly into your workflow. Whether you’re analyzing pages, improving accessibility, or experimenting with AI, you now have the foundation to build anything you imagine.

And despite how essential extensions are, creating one is very simple – it’s just HTML, CSS, and JavaScript with browser APIs.

In this tutorial, we are going to learn about Chrome extensions by building an Advice Generator extension with Manifest V3 (MV3), the latest and most secure architecture for Chrome Extensions. You can move along to see what we'll build here.

Table of Contents

• What are the Key Components of a Chrome Extension?

• How to Build an Advice Generator Chrome Extension

• The Benefits of Manifest V3

• How to Debug Your Chrome Extension

• Conclusion

What are the Key Components of a Chrome Extension?

Chrome extensions are incredibly powerful tools that can add custom functionality directly into your Browser experience to transform how you use the web.

Before we write any code, let's understand some key components:

• Every extension starts with a manifest file. This JSON file tells Chrome everything it needs to know about an extension: name, version, permissions, and files

• The user interface is built with HTML, CSS, and JavaScript. It's essentially a mini webpage that lives inside your browser

• Finally, there's the service worker which runs in the background and fetches data from external APIs. In Manifest V3, service workers have replaced background pages

How to Build an Advice Generator Chrome Extension

Here’s a look at what we’re going to build:

This design is by Frontend Mentor.

Prerequisites:

To follow along with this tutorial, you need:

• Basic understanding of HTML, CSS and JavaScript

• A Chrome browser

• A text editor

When structuring an extension project, the only prerequisite is to place the manifest.json file in the extension's root directory.

Testing Your Chrome Extension (Load Unpacked)

Before we start building, you’ll want to see your progress after each file to catch any issues early. Here’s how to load your extension into Chrome for testing:

1. Go to chrome://extensions to open the Chrome Extensions page.

2. In the top right corner of the Extensions page, toggle the Developer mode on.

3. Click the Load unpacked button that appears.

4. In the file dialog, go to the root folder of the extension and click Select Folder.

Your extension should appear. If its icon does not appear in your browser's toolbar immediately, click the puzzle icon in your toolbar and pin it.

Now let's start by defining our extension's identity in the manifest.json file.

The Benefits of Manifest V3

The manifest.json is the heart of a Chrome Extension. Written in JSON (JavaScript Object Notation), it provides Chrome with everything it needs to know about your extension.

Think of it like a passport with visas and Chrome as the immigration officer verifying identity and access.

Manifest V3 (MV3), brings better performance, security, and reliability to extensions. MV3 uses service workers that activate only when needed, improving battery life and preventing extensions from slowing down your browser.

Let's break down each important field:

• manifest_version is the most critical line. Give it a value of 3 to tell Chrome you're using Manifest V3.

• name, version, description define your extension's basic identity.

• action is a Manifest V3 field that controls what happens when someone clicks your extension's default_icon in the toolbar. The default_popup points to your HTML file, so clicking the icon opens that page in a small popup window.

• permissions tells Chrome what your extension needs access to. We're using host permission https://api.adviceslip.com/* so our extension can fetch advice from that API. Without it, the extension would be blocked from making those requests. This might seem overly cautious, but it's a security measure that protects users.

• background points to your service worker script. The service_worker field tells Chrome that service-worker.js should run in the background.

Step 1: Create a Manifest 3 File

Going by the explanations of the various parts of the file above, here's what our manifest.json file would look like:

{
  "name": "Advice Generator",
  "description": "Get a fresh piece of advice whenever you need it!",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "index.html",
    "default_icon": "/icons/icon-dice.png"
  },
  "permissions": [
    "activeTab"
  ],
  "host_permissions": [
    "https://api.adviceslip.com/*"
  ],
  "background": {
    "service_worker": "service-worker.js"
  }
}

You might see activeTab in other extension examples. While we don't strictly need it for this, it's worth knowing about. It gives temporary access to whatever tab the user is on, but only when they click the extensions icon.

The image below will be the result of running our manifest code above:

Step 2: Create the HTML and CSS Pages

Now that our extension has its identity and permissions defined, let's move on to building the user interface starting with an index.html page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Advice Generator</title>
    <link rel="stylesheet" href="style.css">
    <link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;800&display=swap" rel="stylesheet">
</head>
<body>
    <main class="advice-card">
        <h1 class="advice-id">ADVICE #<span id="advice-id-number"></span></h1>
        <p class="advice-quote" id="advice-quote">
            “It is easy to sit up and take notice, what's difficult is getting up and taking action.”
        </p>
        <div class="divider">
            <img src="icons/pattern-divider.png" alt="Divider pattern">
        </div>
        <button class="dice-button" id="generate-advice-btn">
            <img src="icons/icon-dice.png" alt="Dice icon">
        </button>
    </main>
    <script src="index.js"></script>
</body>
</html>

Now, let's bring the design to life with a style.css file in your root directory. We'll set up the overall body styles, position the card, and style all the elements within it.

:root {
    /* Define colors from the Frontend Mentor style guide */
    --clr-light-cyan: hsl(193, 38%, 86%);
    --clr-neon-green: hsl(150, 100%, 66%);
    --clr-grayish-blue: hsl(217, 19%, 35%);
    --clr-dark-grayish-blue: hsl(217, 19%, 25%);
    --clr-dark-blue: hsl(218, 23%, 16%); 
    /* Typography */
    --ff-manrope: 'Manrope', sans-serif;
    --fw-regular: 400;
    --fw-bold: 700;
}
body {
    margin: 0;
    padding: 0;
    font-family: var(--ff-manrope);
    background-color: var(--clr-dark-blue);
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    min-width: 30rem;
    box-sizing: border-box;
}
.advice-card {
    background-color: var(--clr-dark-grayish-blue);
    border-radius: 0.5rem;
    padding: 1.5rem 1.5rem;
    width: 60%; 
    text-align: center;
    position: relative;
    box-shadow: 0 5px 20px rgba(0, 0, 0, 0.2);
    margin-bottom: 70px; 
}
.advice-id {
    color: var(--clr-neon-green);
    font-size: 0.8em;
    letter-spacing: 4px;
    text-transform: uppercase;
    margin-bottom: 20px;
}
.advice-quote {
    color: var(--clr-light-cyan);
    font-size: 1.75em; 
    font-weight: var(--fw-bold);
    line-height: 1.4;
    margin-bottom: 1.2rem;
    padding: 0 15px;
}
.divider {
    margin-bottom: 35px;
}
.divider img {
    max-width: 90%;
    height: auto;
}
.dice-button {
    background-color: var(--clr-neon-green);
    border: none;
    border-radius: 50%;
    width: 2rem;
    height: 2rem;
    display: flex;
    justify-content: center;
    align-items: center;
    cursor: pointer;
    position: absolute;
    bottom: -1rem; 
    left: 50%;
    padding: 1rem;
    transform: translateX(-50%);
    transition: box-shadow 0.3s ease-in-out;
}
.dice-button:hover {
    box-shadow: 0 0 40px var(--clr-neon-green);
}
.dice-button img {
    width: 2rem;
    height: 2rem;
}

The image below will be the result of running our HTML and CSS code above plus the initial manifest:

With the HTML and CSS done, our extension's visual aspect is complete. Next, let’s give it life by writing the JavaScript that handles fetching new advice and updating the display.

Step 3: Add a Service Worker

In Manifest V3, the core background logic for an extension lives in its Service Worker. Unlike the persistent background pages of Manifest V2, in V3 Service Workers run only when needed, such as in response to a message from index.js or a browser event.

Our service-worker.js will have these roles:

• Listen for a request from index.js (when the user clicks the dice).

• Fetch a new piece of advice from the Advice Slip API.

• Send that advice back to index.js to be displayed.

Create a file named service-worker.js in your extension's root directory.

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === "fetchAdvice") {
    fetchAdvice().then(adviceData => {
      sendResponse({ advice: adviceData });
    }).catch(error => {
      console.error("Error fetching advice:", error);
      sendResponse({ error: "Failed to fetch advice" });
    });
    return true;
  }
});
// Function to fetch advice from the Advice Slip API
async function fetchAdvice() {
  try {
    const response = await fetch("https://api.adviceslip.com/advice");
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    return data.slip; 
  } catch (error) {
    console.error("Could not fetch advice:", error);
    throw error; 
  }
}

Message Handling in Service Workers

Since Service Workers don't have direct access to the DOM of your index.html page (and vice versa), they communicate using message passing. As you can see in the code above, the user clicks the dice in index.html, and index.js will send a message to service-worker.js asking for new advice. The Service Worker will then fetch the advice and send it back in another message.

chrome.runtime.onMessage.addListener listens for incoming messages and sendResponse replies.

Our Service Worker is now ready to fetch advice. The next step is to make our index.js interact with it.

Step 4: Add App Functionality

First, we'll create our index.js file. This script is responsible for all the user-facing logic. It will handle the user's interaction (clicking the dice), send a message to our service-worker.js to get new advice, and then update the index.html with the fetched advice.

Our index.js will perform the following steps:

1. Reference the HTML elements where we'll display the advice ID, quote, and dice.

2. Set up an event listener for when the dice is clicked.

3. Send a message to the service-worker.js to request new advice.

4. Receive the advice back from service-worker.js and update the content on the index.html page.

// Get references to our HTML elements
const adviceIdElement = document.getElementById('advice-id-number');
const adviceQuoteElement = document.getElementById('advice-quote');
const generateAdviceBtn = document.getElementById('generate-advice-btn');
// Function to request advice from the Service Worker
function requestNewAdvice() {
  chrome.runtime.sendMessage({ action: "fetchAdvice" }, (response) => {
    if (chrome.runtime.lastError) {
      console.error("Error sending message:", chrome.runtime.lastError);
      adviceQuoteElement.textContent = "Error: Could not get advice.";
      adviceIdElement.textContent = "---";
      return;
    }
    if (response && response.advice) {
      adviceIdElement.textContent = response.advice.id;
      adviceQuoteElement.textContent = `“${response.advice.advice}”`;
    } else if (response && response.error) {
      console.error("Service Worker error:", response.error);
      adviceQuoteElement.textContent = `Error: ${response.error}`;
      adviceIdElement.textContent = "---";
    }
  });
}
if (generateAdviceBtn) {
  generateAdviceBtn.addEventListener('click', requestNewAdvice);
} else {
  console.error("Generate advice button not found!");
}
document.addEventListener('DOMContentLoaded', requestNewAdvice);

With index.js in place, our Advice Generator is now ready as you can see in the GIF below:

The next crucial step is to know how to debug your extension, should anything go wrong.

How to Debug Your Chrome Extension

Chrome provides excellent debugging tools to help troubleshoot extensions. Always follow these essential steps:

• Reload your extension after making changes (especially to manifest.json or service-worker.js) by clicking the refresh icon on chrome://extensions.

• Check your manifest.json for typos – missing commas or brackets will break everything.

• Verify your API URL and make sure you have the right permissions listed in manifest.json.

Debugging the Main HTML and JS Pages

This is likely where you'll encounter most of your initial JavaScript or HTML/CSS issues.

1. Open the extension and right-click anywhere in the popup to Inspect.

2. Check the Console tab for JavaScript errors from your index.js file.

3. Use the Elements tab to inspect your HTML and tweak CSS styles in real-time.

Debugging the Service Worker – Crucial for MV3

The Service Worker runs in the background and has its own separate DevTools.

1. Go to chrome://extensions.

2. Click the Service worker link underneath your extension or the Errors button.

3. Check the Console and Network tabs for service worker and API errors respectively.

Conclusion

Congratulations, you've just built a Chrome extension using Manifest V3. You've created a user interface, implemented background processing with a service worker, and established communication between different parts of your extension. These skills are the building blocks for any Chrome extension, no matter how simple or complex.

Here are some helpful resources:

• MDN on Browser Extensions

• Chrome Devs on Chrome Extensions

Extensions can add a variety of functionality to the browser, including providing tools for web development, adding features to the browser interface, and changing the behavior of web pages.

We just published a course on the freeCodeCamp.org YouTube channel that will teach you how to create your own Chrome extension with JavaScript.

By the end of this course you will understand how to create a modern Chrome extension. You will learn how to create the extension using the new iteration of the web extensions platform, called Manifest V3.

To follow along, it is best to have a basic understanding of JavaScript and DOM manipulation.

Raman Hundal created this course. Raman is a great instructor and he works for Pieces.app. Pieces.app provided a grant that made this course possible but you don't need to use their extension to follow along.

The extension you will create in this course is a YouTube bookmarker. It will make it so anytime you navigate to a YouTube video page an icon will appear on the video player to allow you to bookmark a particular timestamp on the video.

Watch the full course below or on the freeCodeCamp.org YouTube channel (1-hour watch).

Transcript

(autogenerated)

If you want to create your own Chrome extension, you're in the right place.

In this course, Rahman will teach you how to create a Chrome extension using the new iteration of the web extensions platform, which is called Manifest v3.

Rahman is a great instructor.

And he works for pieces that app pieces that app provided a grant that made this course possible, but you don't have to use their extension to follow along share in the comments what type of Chrome extension you want to make.

Now the reason I want to teach about this particular topic is I've created two web extensions in my career.

The first is for a previous company, where my extension generated a significant amount of revenue for the company.

And the second for my current company pieces, where our web extensions play a critical part of our product stack, and help developers across the globe boost their productivity.

I'm going to be using the pieces web extensions and integrations quite a bit in this video.

So if you're interested in downloading an AI coding assistant that helps you save and reuse code snippets, convert screenshots to code, and more, go ahead and download pieces in the description.

And you can totally follow along.

So during my journey as a Chrome extension developer, I did often notice that tutorials and StackOverflow answers were using outdated versions of the web extensions platform.

My hope for you after you leave this video is that you have a resource to create a modern Chrome extension, and you understand the difference between the newer version of the web extensions platform manifest v3, and older versions.

Now, before we get started, there's going to be three prerequisites to this course, the first is required, and it's that you have a basic understanding of JavaScript and DOM manipulation.

The second is optional.

If you want to follow along with this video and code alongside with me, you can go to the description below, I'm gonna have a link to my GitHub repo, go ahead and get cloned that and you'll be able to follow along.

The third is also optional.

If you totally want to follow along, you can go ahead to pieces dot app and install a pieces IDE integration along with the pieces Web Extension, and you'll be able to use pieces exactly the way I do in this video.

With that, let's get started.

So as I mentioned before, the extension we're going to create as a YouTube bookmarker.

Basically, anytime you navigate to a YouTube video page, an icon will show up on your YouTube video player to allow you to bookmark a particular timestamp on any video.

So let me show you how that's gonna work.

If you're on a YouTube video page, you're gonna see this item at the bottom right, you can go ahead and click that.

And if you navigate to your chrome extension icon at the top, right, I've pinned, so it's showing in the toolbar, you're going to see a new timestamp already had one timestamp for 15 minutes, I added one with an hour 18.

I can go ahead and delete this one because I just decided I don't want it.

And our extension is going to give us that ability to do that.

Now if I want to go back to my 15 minute timestamp, you can click the play button.

And it goes directly back to that particular timestamp.

I can also delete this one too.

And when there's no bookmarks to show, it's going to say there's no bookmarks to show.

Now we're going to add one, just so we have one on this video, and I can show you how storage works.

I'm going to navigate to a new video.

And in this video, we have no bookmarks.

So it says there's no bookmarks to show.

But if we go back to our previous video where we saved a bookmark, it's going to load that previous bookmark.

Now the last thing is if you navigate to a non YouTube video page, it's going to say this is not a YouTube video page in the extension UI.

And that's basically all the capabilities of this chrome extension we're going to build out here, there's going to be a lot more you can do on your own afterwards.

Now I also want to mention the reason we're working on creating this extension in particular, is because it's going to show you all the major parts of creating a Chrome extension, it's going to show you how to work with a content script to manipulate the DOM.

It's going to show you how to create a UI for your extension.

And it's going to show you how to use service workers as background scripts, which is a major part of the ship from manifest v2 to manifest v3.

And to start working on the extension.

Once you get cloned my repo, you can go ahead and click on the puzzle piece in your Chrome browser at the top right click Manage extensions.

I'm going to go ahead and remove my extension show I can show you how it works.

And you're going to see this developer mode option at the top right go ahead and toggle that so it's on click Load unpacked, then go to the repo that you get cloned in mind with the boilerplate code.

Go ahead and load that.

And we're going to see our extension here.

If we Click on this puzzle piece and pin it.

What we're going to see is this basic UI, it's just going to say your bookmarks for this video with no bookmarks, and it's just going to show up everywhere.

This is the default messaging in the boilerplate code I supplied and the boilerplate code will also contain all the files you need to follow along.

The best place to start with creating our extension is the manifest dot JSON file.

This file is a JSON file where we can specify what version of the extensions platform we will use, among other information that is going to serve as default for loading in our extensions.

Also, every extension you would want to create whether it's Safari, Mozilla, or any chromium base extension will need a manifest dot JSON file.

And it's probably the single most important file in your extension, because it simply just won't work without it.

In our boilerplate code already added the manifest dot json file, so we don't have to spend too long writing it out, I think it would be especially helpful if I just point out some of the things that you should note, in case you're creating your own extension.

So let's take a look here, as you'd suspect, there's a name, there's a version number and a description.

And basically, the version number is going to populate when you loaded in the extension, the name you see is also going to be the name of the extension when you load it in.

And the description is pretty self explanatory.

It's just a description of what the extension does.

Now things get more interesting with the permissions.

The permissions will be different depending on whatever Chrome extension you're building.

For this particular extension, we're going to request two permissions, which is going to be the permission to use the Chrome dot storage API, and the chrome dot tabs API.

The chrome dot storage API is to store things in the user's browser for the extension.

And the second permission, which is a chrome dot tabs API, is what helps us access our browser's tab system.

So we can read the tab for the extension.

This is basically going to help us identify what browser tab the user is currently using, and grab the URL to see if they are in a YouTube video page for our extension.

Now, the host permissions just give you the ability to send cause requests to certain host names.

Our extension only deals with YouTube pages.

So I have a match pattern written here just for YouTube.

The service worker, as I mentioned before, there's a big change between extensions, v2, and v3.

And one of the big changes is the use of a service worker.

As you can see here, the other is the ability to use promises.

But let's just focus on service workers.

For right now.

Service workers are just a JavaScript file that runs separately from the main browser thread.

This means that your service worker would not have access to content of a webpage, since it is separate from main processes.

However, your service worker does have capabilities to speak to your extension using the extensions messaging system, which we will see and use in our bookmarking extension.

The next thing I want to point out is the content scripts.

The content scripts are just files that run in context of the webpages we're on.

We're going to use this to manipulate the DOM of our webpage that our extension is looking at.

And here we're just specifying that our content script is represented by our content script J S file.

As you can see, with the J s colon content script dot j s, the last thing I want to point out is the pop up dot HTML file down here, under default pop up, this just specifies which file was served as our UI.

In our case, we've specified the pop up dot HTML file, and in that file, we specify that the corresponding file that helps it with its interactivity is a pop up.js file.

With all that out of the way, let's get to coding the actual extension.

We're now finally going to start writing code to make our extension work.

For us even test the extension, we have to add the button of the YouTube player that will allow us to save bookmarks with timestamps.

So in order for us to add a button on the YouTube video player will have to manipulate the DOM of the web page we are on.

What that means is we'll have to write our logic in our content script file, which operates in the context of the webpage, as I mentioned before, so let's go ahead and add some code to our content script file.

We're going to go ahead and add the following variables YouTube, left, controls, and YouTube player one is going to be for accessing the YouTube player one is going to be for accessing the controls.

And this is going to allow us to manipulate each of these.

But before we continue writing the logic to do DOM manipulation in the context strip, we also have to think about how our extension is even going to know when we've navigated to a new web page.

And we need to know this so the content script knows to execute logic to add the plus i Call to add bookmarks for our extension.

Let's go ahead and go in our background.js file now.

And what we want to do here is listen to any updates in our tab system and find the most recent tab or the tab that we're on currently and see if it's a YouTube page.

So we're going to have a listener, that's going to listen to tabs.

And if you remember, we got permissions to access the Chrome tabs API.

And we're going to listen for an update to tabs.

The parameters were given is a tab ID and a tab.

What we're going to do from here is see if there's a tab URL, and if there is a tab Euro.

Let's see if that Euro includes youtube.com/watch.

The way I came up with that is if you look at our YouTube video, every individual video has YouTube slash watch.

And we just want to make sure we're on a page that has that specifically as a URL, then what we want to do is set our query parameters.

And we're going to use query parameters as a unique ID for each video.

So we can grab it from storage, you'll see what I mean in a second, and I'll show you.

So we're going to do that by using the JavaScript split method.

What that means is basically after this question mark query parameter, we're going to grab this value.

And this is going to be our unique video value this right here after the equal sign.

And every video on YouTube has a different value right here.

So it's a pretty unique key that will help us store videos uniquely as well in our storage, and it's consistent.

So then we're going to add your URL parameters.

And this is just an interface to work with URLs URL search params.

And the final thing we want to do is there's a messaging system that happens between the extension, we're going to send a message to our content script that basically says a new video is loaded.

And this is the video ID of that video, and the video ID being that unique video value that we saw in the URL on YouTube.

And this tab, Id send message usage that I'm doing right here is all directly from documentation.

The Send Message takes a tab ID, it takes a unique object.

So right now I'm going to type type.

And this is a type of event is a new video event.

And then a video ID value, which is going to be URL, parameters, dot get v.

So if we're doing URL dot get D, it's going to grab this right here.

And that's basically going to be the code for that send message takes a tab ID, it takes an object and then it can also take a callback function.

This object right here doesn't have to be type or video ID, it could also be something random, like I could literally pass this and the content script will have access to random, and then the string random.

In our case, the only thing that's applicable is the type of the event and then the video ID, which is a content script needs.

Now in our content script, we're going to add a listener that is going to listen to any of those incoming messages, we need to be able to listen to that background.js message.

So to do that, we're going to end up writing the following code to add that listener, so we're going to say on message add listener.

And this is going to accept three parameters.

So an object a sender, and a response.

And the response is, when a message is being sent to the content script, we can also send a response back where the message is coming from.

So I'm going to destructure those values we're getting and if you remember, the way I'm deconstructing Type value video ID is basically we're given a video ID right here.

Later on, we're going to grab a value as well, and I'm just destructuring.

So each of these are its own variable.

So it's a If type is equal to new, so if the type of event is new video loaded, which we're getting from the background.js file, we want to be able to set current video, which will be a global variable in the content script as the video ID, and then we want to call a function to handle any actions with new video.

So we're going to call a new video loaded function.

And let's go ahead and set current video as a top level variable.

And that's just going to be an empty string.

But it's going to be set as the string set from the background at js file, once the message is received on this end, so let's go ahead and actually see if this works at all.

I'm gonna go ahead and just console dot log your parameters.

I'm gonna give this a reload.

Open this, let's inspect it.

And we ever URL search parameters.

So we know we're getting our URL search parameters now.

Great.

So so far, things look good.

Now, what we want to do from here is create that new video loaded function.

And after we create this function and all the functionality surrounding it, we should see the YouTube player button on the YouTube video.

So let's go ahead and do that.

So what we're going to do is create this function that we have right here called New Video loaded.

And what we probably want to do is check if a bookmark button already exists, I know the class name that this item has, it's called Bookmark button because I wrote the CSS code that's going to style this whole extension.

So you could just copy this part right here.

But this is just some native Dom, slash JavaScript methods that we can use.

It's actually MB by class name.

And it's going to return an HTML collection.

So what we're going to do is grab the first element that matches this class name, bookmark button.

And it's just going to exist on every single YouTube video page.

So if we want to test that, we could just say console dot log bookmark exists.

And let's reload this page and inspect it.

Actually, let's reload our extension as well.

reload this page inspect, we're probably going to get undefined this is exactly what I expected.

Because we don't have any logic surrounding the Bookmark button yet.

And also, we're not even setting a bookmark button right now.

So if the Bookmark button did exist, we would get true, it does exist, but we're getting undefined right now.

So what we want to do if we're getting that undefined or false value that a bookmark button does not exist, is add some logic to say, hey, let's add this bookmark button to any YouTube player.

So we're going to create an image element.

That is going to be the image we click on for bookmark buttons.

As part is in, we're going to add a couple of attributes.

The first thing we're going to want to do is pull the image that we're using, which is our assets slash bookmark.

PNG, you already have this if you're following along with the boilerplate code.

The second thing we want to do is add a class.

And the way we're going to add this class is basically make it pretty dynamic here.

So we're gonna add a YouTube button class with a space and then we're going to add a bookmark button class in quotes.

And this is again, just some styling I have that you don't need to worry about right now.

And the last thing we want to do is basically on hover, we want to make a title show.

So we're just gonna say the title is click to bookmark, current timestamp.

And this is just a UI thing.

You'll see this in a bit.

Next, what we want to show is a way to grab the YouTube controls.

So these are the YouTube controls over here, we want to be able to grab these left controls, so we can add a bookmark button right here.

So let's go ahead and find out how to do that.

I already know how to grab this.

So I'm going to show you how this works.

You can inspect elements right here and find what elements they exactly are.

But basically, we're going to use native JavaScript methods like we have done previously to grab those controls and insert our button.

If I do document dot get elements by class name.

And I grab YouTube left controls, we should get an element back, which is going to be this div class over here.

And you can see that it gives us all the left controls over here, where we're going to add our button.

And the second thing we're going to want to do is grab the YouTube player as well.

And that's one of the global variables we set in our content script.

And we can also do that by writing document dot get elements by class name.

And then there's this video stream class.

And we're going to grab the one at the zero with index.

And it grabs a whole YouTube component right there.

So now we know the two elements in the DOM we need to manipulate.

But let's set those elements.

First, we're going to do exactly what we saw in our content over there.

Document get, actually, I'm just gonna go back and copy these way easier, so don't make a mistake.

And then the second one is going to be YouTube player.

Go back and copy that.

Okay, so after this, what we're going to want to do is add that bookmark button and we grabbed the controls, you saw that row in the player, we want to add it to that row.

So we're going to type out YouTube left controls to get those left controls we stored in a variable.

And to use this native JavaScript method we can use called append child, which is going to append this bookmark element inside that row.

And then the second thing we're going to want to do is probably add a listener to listen to any clicks on our icon.

So there's a correction I want to make to this portion of the video, before we continue, it's going to be very important in order for your extension to work functionally.

And it's only one line of code, but it's going to make such a big difference.

I'm also going to explain an important concept of Chrome extensions that I neglected while I was writing this, which is that in our manifest json file, we have a match pattern for our content script.

And basically the match pattern, we currently have checks if any youtube.com video is loaded.

And if it is, we're injecting our content script into the context of that web page.

So basically, what that means is, anytime a youtube.com page shows up, we're running a bunch of logic using our content script.

But the problem right now is that our background.js file is telling us when a new video is loaded.

And the event listener we're using is on updated, which is just checking if this URL is updated.

If you refresh this page, the URL is not updated.

So this button actually isn't going to show up.

And if you continue coding without this fix right here, you're gonna see some edge cases that you might not like.

So let's go ahead and fix this, we're going to do a super simple fix.

It's not the best fix in the world, but it will fix the problem here.

We're just going to call a new video loaded anytime our content script matches youtube.com.

And what this is going to do is call this new video loaded function anytime we hit that match pattern.

The downside of this is now if the background script sees it as a new video using the on updated event listener, and there's a condition that content script is injected, we're going to hit this or call this new video loaded function twice, you can fix this pretty easily by just adding a conditional make sure that doesn't happen.

But to make sure everyone is able to follow along with this correction, I will not be doing that here.

And we'll just only be inserting this one line of code calling the new video loaded function.

Luckily, the only thing our new video loaded function is doing is adding the Bookmark button to the YouTube player.

So there's going to be no negative implications to calling it twice.

Since we have a condition that checks if the button is already on the player.

It's just not the most efficient implementation, which is fine for the sake of this tutorial.

With that, let's continue with the rest of the video.

There we go, we have the button right there.

But right now, if we click the button, it's not doing anything.

And there's a reason for that.

The reason is that we don't have any event listener listening to click on this particular byte.

Let's go ahead and add the code for that.

So what we're going to do is add an event listener to listen to a click for the button.

And we're literally going to use the add event listener method, listen for a click, and then call a function called add new bookmark event handler.

And this is a function we have not coded yet.

So to make this function work, we're going to have to do the following.

We're probably going to have to figure out the timestamp of the video at which point someone presses the button.

This is basically going to help us figure out what our bookmark should be saved as in storage according to its timestamp.

So how are we going to do that? How are we going to figure out the YouTube video timestamp.

Again, YouTube makes this pretty accessible, it can be found as an attribute.

So what we're going to want to do is grab the YouTube player.

And we already have a global variable that has it.

But I'm just going to grab it again.

So we can see how to do this in the console, I'm going to create a YouTube player variable in our console.

Okay, now we have it saved.

And then on YouTube player, there's going to be a property called current time.

And it's going to give us the current time in seconds.

And in order for us to save our bookmark, according to hours, minutes seconds, we're probably going to also have to create a function that converts seconds into a standard time of how it's displayed in YouTube.

So let's go ahead and start with all those things.

We're gonna go ahead and add the function, add new bookmark event handler.

And we're going to use the exact property we saw in our console, YouTube player dot current time, which is going to give us the current time.

And we're going to say okay, now, this is only called when a new bookmark is made.

So let's create a new bookmark variable.

And this is going to be an object that has the time of the bookmark and a description.

And the description is just going to end up being the title that's going to be displayed in the Chrome extension.

So it's going to be a dynamic description and skins a bookmark at current time.

However, the problem is that this is in seconds, as we said before, so we're going to have to convert this.

So we're going to use a function called get time.

I'm just going to insert it using pieces.

So I'm going to do is go over to this time function here.

Insert snippet.

And there it is.

So now I'm able to convert my seconds into time.

And then the last thing I want to do here is sync it to Chrome Storage.

And what this is going to do is set Chrome storage with each bookmark.

So basically, each video, according to its video identification number that we're grabbing from the URL will also map back to a set up bookmarks in Chrome Storage.

So to do that, we're going to do Chrome storage sync.

And again, if you're interested in this, you can look in documentation to find out what this function takes.

Current video, it's important to remember that things need to be stored in JSON in Chrome Storage.

So I'm going to do JSON stringify.

All my current video bookmarks, so I'm actually going to add it A variable up here that's going to store all current video bookmarks in an array.

And I'm going to spread that.

So we can add a new bookmark to those set of current video bookmarks.

And then the last thing I want to do here is sort bookmarks by their save timestamp in our Chrome Storage.

So we're going to sort by time, and this is just coming from this right here, every bookmark is going to have a time and a description.

So we're going to look at that and sort accordingly.

Great.

Now, if we reload our extension, we're going to see if it works as expected.

And the way to see that is basically console dot log, this new bookmark, let's do it.

Great.

That time it worked, we just had to give it another reload.

And we got a time in seconds and a description.

Now the final thing I want to do is complete this file before we go to the UI.

And we want to make this fully functional to fetch all bookmarks when a new video is loaded.

To do this, we're going to grab asynchronously, all bookmarks from Chrome storage, which means I'm going to write a promise that resolves once we retrieve all bookmarks.

So that code is going to look like this.

I'm going to create it at the top here.

And I'm going to say const fetch bookmarks.

And I want to return a promise.

So we can resolve this asynchronously.

And within that promise, I'm going to fetch from Chrome Storage.

So I'm going to do a Chrome storage sync and we did a set before to set Chrome Storage, we're going to get this time our current video it takes an object.

And we're going to resolve to find any bookmarks when indexing using our current video.

So basically look in storage to see if our current video has any bookmarks, or if it exists in storage.

That's what's happening right here.

If it does exist, we're going to JSON dot parse it because we JSON dot Stringify before, if it doesn't, what we want to do is return an empty array.

And this should work.

And we're really only going to add these in two places, which will be in our new video loaded function.

So we're going to make this async.

And we're gonna add a fetch bookmarks.

So actually, we're just going to add this to our current video bookmarks variable.

And call a weight fetch bookmarks.

async await is going to resolve this promise.

And then the second place we want to add this is to our add new bookmarks event handler.

To basically handle this case, and make sure we're always using the most up to date set of bookmarks when destructuring.

So we're gonna do current video bookmarks equals the weight, veg bookmarks.

And also make this async.

Awesome.

So for right now, we finished everything we need for our content script file, obviously, things aren't going to show in the UI.

And we could check that out right here.

And as you can see, there's nothing in the UI because everything we've been doing so far has been manipulating the DOM right here to add the icon.

Add some logic to get us ready to create a UI for our extension.

Let's go ahead and start making some UI components show starting out with some bookmarks from clicking that addition button in the YouTube player that we added.

Now, the first thing we need to figure out on any given page is if it's a YouTube video page or not, if it is, we're going on one of fetch any bookmarks we may have from Chrome Storage.

And if it's not, we'll just want to display some messaging saying it's not a YouTube page.

If you open the Chrome extension on a page that is not YouTube.

So to do this, we're going to add a utility function that's going to allow us to decipher that logic.

So we're actually going to grab our utility function to find the active tab that the user is on through Google Chrome documentation.

I'm going to go ahead and use this example right here, which helps us retrieved a currently focused tab from the Chrome documentation.

And since I have the google chrome pieces extension over every codeblock, whether it's in documentation or Stack Overflow, I'm able to directly save on pieces with this icon that shows up at the top right of any code block, I'm going to go ahead and save it.

And then I'm going to go back to my VS code and refresh my pieces tree, I can go ahead and insert this snippet, which is the newest one, and I'm just going to rename this snippet to active tab Chrome.

Amazing and pieces automatically classified this as JavaScript, because it was able to decipher that from some machine learning.

I'm gonna go ahead and delete this background.js comment.

And awesome, we now have a function that grabs the current tab.

But also, I want to make sure I'm exporting this function.

So I'm going to add export.

And then what I want to do is open up the pop up.js file.

And over here, we're going to want to import that function at the very top.

So we can use it here.

So I'm going to import Get active tab URL from utils dot j, s, and I actually don't think the documentation called it this.

So I'm going to go ahead and change the function name, so it matches.

So go to utils.js.

Change that thought, awesome.

Now, the event we want to listen to when opening the pop up.js file is the DOM content loaded event, which is right here.

This event is a native window event that fires when an HTML document has initially been loaded.

It's essentially when we want to load all our bookmarks and show them.

So we're going to type the following to do so what we're going to do is grab our active tab function first.

And we're going to look at the user's current active tab, which we already have the function for from in the utiles.

It's an async function.

So we're going to async await this.

And then after that, we're going to grab the query parameters to help us identify the video.

If you remember, each YouTube video has a unique identifier.

After the question mark, where the query parameter, we're going to grab that, we're going to use a URL search params to be able to get the unique identifier for each video.

And to get the unique identifier, we're going to create it current video variable and do URL parameters dot get V.

And this is just based off of what the YouTube video URLs look like.

Now, our active tab URL should have youtube.com/watch Because any specific YouTube video always has this in its URL.

And we want to make sure we're watching a YouTube video when our Chrome Extension has any logic with bookmarks.

And we want to make sure this current video variable is truthy meaning is get actually returned something other than undefined or any falsie value.

And then what we want to do is we want to get any current video bookmarks from Chrome storage.

If you remember, we're setting Chrome storage with the current video as a key and then all the bookmarks as a value that is JSON ified.

And in order for us to retrieve those bookmarks, we need to use a Chrome Storage API to get them.

So to do that, we're going to grab the video bookmarks using Chrome storage sync get.

And we're going to get it with the current video unique identifier, which is the YouTube videos unique identifier in the URL.

And then, we are going to set a current video bookmarks variable which is going to contain all those JSON ified current videos.

And in order for us to pass this to any function or write some custom logic to show bookmarks, we're going to have to JSON dot parse any bookmarks that are saved in Chrome Storage since it's in JSON, and we can't really work with that.

But if there are no bookmarks or chrome searches and return anything, we're just going to want to return an empty array.

Now, we're going to have to pass this over to the view bookmarks function, which is basically going to help us view any bookmarks in our extension, that Chrome Storage dot get returns.

But before that, I'm just going to put a comment right here.

So we remember, we want to handle this else condition, which basically is for the scenario where we're not on a youtube.com video page, or current video returns a falsie value.

So what we're going to want to do is add a message that says this is not a YouTube video page.

And let's just go back to chrome to look at what that might look like.

So this is our UI Currently, we have this container class right here that encapsulates and will eventually encapsulate all the bookmarks we have, it has this container class name in it, what we're going to want to do is get that class name.

So we're just going to do this in the console before we actually do in code just to make sure it works.

The class was called container.

And that's just from the CSS in the boilerplate, so you don't have to worry about it, or the HTML or other.

So when we wrote this document that get elements by class name container, and then grab the first element in the HTML collection, we get this element right here, which is containing all these other elements within it.

And what we want to do here is basically specify in the HTML on pages that are not youtube.com.

So this is actually a YouTube video page.

We don't want to display this message.

But I just want to show how this is going to look, we're going to want to put a new div class that says, This is not a YouTube video page.

And let's just see if that works.

Will this change the extension the way we want it to? Container is not.

So what we need to do over here is actually encapsulate this in a variable.

We're gonna set this equal to container.

And now let's try that.

And change the extension to show that this is not a YouTube video page.

So the way we're going to do this dynamically in our code is basically put all the code we just put in our console to test this out within our else conditions.

So every time we're not on a YouTube video page, or this returns a falsie value, we want to show that this is not a YouTube video page when we try to open up the Chrome extension in those scenarios.

So we're gonna say const container equals document dot get elements by class name, right there.

Grab that container class, first element.

And then set the inner HTML, set that equal to div class equals title, title, just add some styling, that's going to make it look slightly nicer.

There's nothing super special about the styling I have.

And since we tested it, there shouldn't be really any surprises here, it should pretty much work as expected.

So let's go ahead and give this extension a reload.

It shouldn't show the message for this page.

It doesn't.

But if we go to a non YouTube page, it's gonna say this is not a YouTube video page.

Amazing.

So let's go back to our code.

And we're going to want to write this view bookmarks function.

So if it does meet the conditions of being on a youtube.com/watch page, and as you can see, that's from any page that has a video page, it has youtube.com/watch on it.

And your URL params dot get the return something so it's a truthy value, we're going to want to view the bookmarks associated with that video.

So let's go ahead and call the view bookmarks function and pass it all the current video bookmarks.

And we're gonna go ahead and write the logic that's going to help us populate the UI with all the bookmarks we grabbed from Chrome Storage.

So to do that, we're going to pass it current bookmarks.

And we're going to set a default argument of an empty array just in case nothing is passed to it.

It's just going To return or show no bookmarks, and we're going to grab a bookmark element.

Again, this is just from the HTML that I have given you.

So it's not anything you need to worry about.

If you want to try this out on your own, you could try it out in the console.

Just to save some time here, I'm just going to write the code here.

And you can go ahead and copy it.

But again, it's just knowing how to work with the DOM and inspecting the elements to figure out how to do this.

What I'm doing right here is basically saying, Okay, if there are any bookmarks, let's just set it to nothing.

So we're not displaying anything, we're going to reset the whole thing, since we're calling this function to view bookmarks.

And we're going to have new bookmarks being passed in, which is the current bookmarks.

And we're gonna say if the current bookmarks length is greater than zero, meaning if there are current bookmarks, and it's just not an empty array.

Let's go ahead and iterate over all those bookmarks, and show them in our UI.

So to do that, we're going to iterate over every bookmark in a loop.

And then, we're going to grab the bookmark through indexing, so current bookmarks.

With whatever iteration we are in the loop.

And then what we're going to have to do from here is call another function, add new bookmark, which is going to add a new bookmark row to our pop up, I'm going to go ahead and remove this comment.

And we're going to add a new bookmark, we're going to pass it the bookmark element up here, which is going to populate all our bookmarks, well, it's going to be where we add each of our rows.

And I'm going to pass it each specific bookmark.

So we're going to add one bookmark at a time and call this function every time we're adding a bookmark.

But before that, what we want to do is if there are no bookmarks to show meaning, current bookmarks is just an empty array.

We're going to want a message that says there are no bookmarks here.

So we're going to set a message using italics.

Saying no bookmarks.

To show before we move on and add individual bookmarks to our pop up, let's go ahead and check if this condition works.

Where there's no bookmarks to show and since we haven't added any bookmarks to this YouTube video that I'm looking at right now, it should work, I want to go ahead and reload my extension.

Yep, there it is no bookmarks to show.

Amazing.

So now we're going to want to finally handle the case where we have bookmarks to show and this is going to allow us to start seeing bookmarks in our UI.

So the first thing we're going to do is go to our add new bookmark function.

And it's going to accept bookmark bookmarks element, and it's going to accept a bookmark.

And then what we're going to do from here is we're going to create two elements.

So one element is going to be for the title, which is going to display in the UI of each bookmark.

And then one element is going to be the whole bookmark element that will contain the title will contain the delete button and will contain the play button.

So let's go ahead and create the bookmark title element.

And then after this one, we're also going to create the new bookmark element, which will encapsulate all these other elements that are part of a bookmark row.

From here, for bookmark title element, we're going to want to display what the bookmark is and give it a title.

So we actually already created the title.

The title is the description of the bookmark.

If you remember in our bookmark object, there's a timestamp and a description.

So we're gonna set our text content to the description, which is bookmark dot description.

And then our class name is going to be bookmark title element dot class name, and that will be set equal to bookmark title and this is just going to add some In CSS, that is already in our boilerplate code.

Now for the general component that is going to encapsulate all the play button, the title, a delete button, anything else you might want to add, we're going to do a couple things, the first thing we're going to do is give it an ID of bookmark element, or bookmark with the bookmark time, and this is going to guarantee a unique ID for each element that is a row.

So if you save any bookmark, what's gonna happen is there's going to be a row associated with each bookmark, which is our new bookmark element.

And there's going to be an ID set for that row, which will be the bookmark along with the time and they'll help us uniquely identify any specific row in the UI.

And that's later we're going to be used to delete elements when we're deleting a specific bookmark.

And then we're going to set a class name, which was is going to help with some styling, that's going to be set to a bookmark class.

And then we're going to set an attribute which is going to help us with playing a video.

Because basically, we're going to want to know the timestamp of any specific bookmark.

So when we play the video, we know where to set the video player at what time we want to send it out and the attribute of the bookmark element will help us find that.

And the final things we want to do here is, since we know the new bookmark element is encapsulating all these other things, we want to append child bookmark title element, so it displays within the new bookmark element.

And then we have this bookmarks element that is passed in.

And we're going to append our new bookmark element, which is this element that's encapsulating all the other things.

Inside that since it's a container.

So now if we go back to our UI, and we give this a reload, just in case, let's just go to a new video.

And if I press plus, in this video, we see a new row, it says bookmark out one hour, 54 minutes.

And we could add another row if we want.

And it gives us that same row, we're going to handle the case of the deletion, there's an ADD, it's just going to set at zero seconds.

Bookmark it 000.

Awesome.

So that works.

So now let's go back work on some additional functionality.

Right now, we have no functionality associated with each bookmark yet, so we can't play any particular timestamped bookmark, we can't delete a bookmark.

And the next thing we want to add is the play button.

So to do this, we're going to add a play button to each bookmark that will go directly to this timestamp that we have saved for each video.

To start off, we're going to have to add a function that is going to add an icon for a play button, listen for a click and call a function or event listener that will perform the logic to set a video at a particular timestamp.

The function will end up looking something like what we're going to code right here in a second.

And we're going to keep it super generic because it's going to be used for both our delete and play functionality.

So the functions are going to take a source attribute an event listener.

And it control parent element.

And when we say control elements in our code, it means the play button, the delete button, we're just calling those control elements.

So we're going to create a control element.

And this is just one particular functionality, we're going to call a singular control element.

So in this specific case, we're going to have a play button.

But again, this is a generic function.

So think of this as like a play button, a delete button we want this singular control element will be one of those.

And then those control elements will be linked to a image in our assets folder.

So if we want to play button, what we're going to link to is assets slash play dot PNG, and our schema super are predictable for this.

So all we're going to do is assets plus SRC plus dot png.

And there's definitely a better way of doing this, you can go back and work on the code after this video.

But we're just going to keep it super simple for right now.

We're going to give it a title that is the same as our source attribute, or what we pass in this source.

So what's going to get passed in here is play, edit, delete, whatever.

And the title will be set to that.

So in this particular case, for play, it will be set as play, we're going to add a event listener.

And that event listener will listen for a click.

And we're going to pass it a function that is going to be performed on that clique.

And the last thing we want to do is there's going to be a container for all control elements.

And we're passing that in into this function.

And we're calling it control parent element.

So we're going to append this singular control element to the parent element.

And the next thing we're going to want to do is add the function call that will add a play button, a title and our event listener to each individual bookmark.

So in the add new bookmark function that we coded earlier, we're going to add a couple lines of code here.

And these couple lines of code are going to add those control elements.

So we're going to go ahead and create the element that's going to hold all our buttons, we're going to call it the controls element.

And it's going to be a div just like these other ones, we're going to keep it super simple.

And then what we want to do is give this some styling.

We're going to add the class name, but controls, and you're just gonna have to trust me on this it exists.

Then what we want to do is set our attributes using a set bookmark attributes function that we created, we're going to pass in play, the event listener is going to be called on Play.

And we're going to code that later.

And then we're going to pass in the controls element, which is going to be the parent element.

And the last thing we want to do is append this to our new bookmark element.

And what we should see now is, this play button is going to show up in our extension.

So let's check this out.

Let's give this a refresh over here.

There we go.

We have the play button in our extension.

But what we're going to notice is it's actually not going to work.

Let's go ahead and play this video.

And we're going to try to get it back to 26 minutes, 51 seconds, it doesn't work.

And the reason it doesn't work is we still need to code the On Play Event listener.

So let's go ahead and do that.

What we're going to do is we're going to target the timestamp attribute that we set earlier.

So again, you could check this out in your console or inspect, if you want to get a visualization of how this is gonna work.

But I'm gonna go ahead and type this for the sake of time.

And we're gonna get that timestamp we set earlier.

And then the second thing we're gonna want to do is grab the active tab, and that's just using the active tab function.

This is an async await function.

So we're going to have to async await it.

And I'm going to add async to make this async function.

So we've actually run into a problem now, we need to send the content script and message to manipulate the YouTube player to set it at the timestamp that the bookmark is placed on.

So in this file, we're going to have to add that message.

Let's go ahead and send a message to the content script.

And this is going to follow the same pattern of how we did it with our background script.

Missing comma there.

We're going to have type of play.

That's going to be our event type.

And then the value is going to be bookmark time.

And then in our content script, we're going to have to be able to read this message.

So what we're going to do is add a condition to our On message listener here, and we're going to say if the type is play.

Let's set the YouTube player time equal to the value that's passed in.

So basically, let's just take a look at this for a second.

If it's sending a message of type play, and the value is the bookmark time, then what we want to do is take that value and set it to the YouTube Players Current Time, which will make it the time of the bookmark.

And let's go ahead and see if this works.

I'm going to go ahead and reload my extension.

And let's go ahead and go to the extension, we have a bookmark at 26 minutes, 51 seconds, it's currently at 48 minutes, 30 seconds.

Let's hit that play button.

It goes back to 26 minutes, 51 seconds.

And now if we also hit this addition button anywhere in the video, we should get a new bookmark, we have two hours, 21 minutes, 22 seconds.

Now let's go forward.

Let's press play here.

And it goes back to that time.

Awesome.

So now our Play button works.

The last functionality we want to build is the ability to delete a bookmark, which will be super similar to what we did for the play button.

The first thing we're going to want to do is go to our POP up.js file.

And we're going to add the delete button to our controls element with the code in our add new bookmark function to set bookmark attributes.

So let's go ahead and do that we're going to pass in delete our on delete event listener, and then the parent controls element.

And since we set the undelete function as the event listener, we need to code some operations that are going to take care of our deletion.

So we already know we're going to use this active tab that we used over here.

So let's go ahead and already create this an async function ahead of time.

Let's grab the user's active tab.

And then what we're going to want to do is grab the timestamp attribute that we set earlier.

And it's going to be the same code from up here.

So I'm just going to copy and paste there we go.

Then what we're going to also want to do is grab the element that we want to delete.

So if you remember, I created a specific ID linked to timestamps, what we're going to want to do is grab elements by the ID so we can delete them.

So bookmark.

Plus the bookmark time will give us the element we want to delete.

And then what we're going to do is delete that element by going to the parent node, and then removing the child which will be the element we want to delete.

And then the final thing we're going to want to do here is send a message to our content script.

Saying we want to perform a deletion type of delete, and then the value is going to be bookmark time.

And there's one final thing we want to do here, this Send Message function from the Chrome's tabs API actually takes a callback function optionally.

And we're going to pass one in which is going to be our view bookmarks function.

And that's just going to refresh our bookmarks, so any deletions show up immediately, then in our content script, we're going to add another condition, which is basically you're going to ingest that Delete message.

So we're going to say else if type equals Delete.

The current video bookmarks will be equal to current video bookmarks.

Filter, and we're going to filter by time.

So the time is not equal to the value being passed in because that's a value we're deleting.

And then the final thing we want to do is sync Chrome Storage.

So if this page reloads, this deleted bookmark does not show up.

We're going to JSON fi, error bookmarks and If that should work, the last thing we want to do is add a way to send the updated bookmarks back to our POP up.js file in order to display the most recent bookmarks, and we'll do the following.

To do that, we're going to send a response of current video bookmarks.

So now we can go ahead and try out deleting a bookmark with a reload of our extension, and it should start working.

So I'm going to go back to our Chrome browser, reload our extension.

And if we go ahead and delete a bookmark, we're gonna see that they're deleted.

If we go ahead and add a bookmark, we're gonna see there's a new bookmark.

It's at a different timestamp the YouTube players a different time.

So if we play, it goes back to the timestamp of the bookmark.

We want to delete again, it's going to delete.

The last thing we're going to want to do is distribute our extension.

However, I'm not going to quite go over that in this video, because Google gives great documentation that serves as a step by step guide on how to go about publishing your chrome extension to the Google web store for anyone to download.

And with that, the videos over you know everything you have to do in order to create a modern web extension using manifest v3, and I'll see you next time.

If you are a Google Chrome user, you've probably used some extensions in the browser.

Have you ever wondered how to build one yourself? In this article, I will show you how you can create a Chrome extension from scratch.

Table Of Contents

• What is a Chrome Extension?
• What will our Chrome Extension Look Like?
• How To Create a Chrome Extension
• Creating a manifest.json file
• Conclusion

What is a Chrome Extension?

A chrome extension is a program that is installed in the Chrome browser that enhances the functionality of the browser. You can build one easily using web technologies like HTML, CSS, and JavaScript.

Creating a chrome extension is similar to creating a web application, but it requires a manifest.json file which we will discuss in the last section of this post.

What Will our Chrome Extension Look Like?

Latest Covid Report of UK-Chrome Extension

As you can see, the above chrome extension displays the latest data on Coronavirus (COVID-19) in the UK. We will be looking into how to create this extension in this blog post.

Here, we will be using the https://api.coronavirus.data.gov.uk/v1/data API in order to fetch data. We will only display the latest record for the simplicity of this post.

The complete source code of this project can be found on GitHub.

How to Create a Chrome Extension

First of all, we need to create an empty folder where we will add our HTML, CSS, and JavaScript files.

Inside the folder, let’s create an index.html file with this HTML boilerplate code:

<!DOCTYPE html>
<html>
<head>
    <title>Covid-19 Stats- UK</title>
    <meta charset="utf-8">
</head>
<body>
</body>
</html>

Now, let’s add a link to the Bootstrap CDN in the head tag. We will be using the Bootstrap framework here so that we don't have to write some extra CSS in this example.

<head>
    <title>Covid-19 Stats- UK</title>
    <meta charset="utf-8">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
</head>

In the demo, we saw that the records are displayed as a table. So now we need to work on creating a table.

<!DOCTYPE html>
<html>
<head>
    <title>Covid-19 Stats- UK</title>
    <meta charset="utf-8">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
    <div class="container mt-3" style="width: 450px;">
        <h2 class="text-center">Covid Latest Report-UK</h2>
        <table class="table table-bordered">
            <thead>
            <tr>
                <th>Date</th>
                <th>Country</th>
                <th>Confirmed</th>
                <th>Deaths</th>
            </tr>
            </thead>
            <tbody>
            <tr>
                <td id="date"></td>
                <td id="areaName"></td>
                <td id="latestBy"></td>
                <td id="deathNew"></td>
            </tr>
            </tbody>
        </table>
    </div>
</body>
<script src="script.js"></script>
</html>

The code above creates a table with a width of 450px. There are four different headings in a table: Date, Country, Confirmed, and Deaths.

Here, you can see that each table data td has been assigned different IDs. We will be using the value of these IDs in JavaScript to update the table data. Also, here we have loaded the JavaScript in the end after loading all the HTML content.

Now, since the table has been displayed, we need to work on writing JavaScript in order to fetch data from the API.

Let's create a script.js file and add the following code:

async function fetchData() {
    const res=await fetch ("https://api.coronavirus.data.gov.uk/v1/data");
    const record=await res.json();
    document.getElementById("date").innerHTML=record.data[0].date;
    document.getElementById("areaName").innerHTML=record.data[0].areaName;
    document.getElementById("latestBy").innerHTML=record.data[0].latestBy;
    document.getElementById("deathNew").innerHTML=record.data[0].deathNew;
}
fetchData();

Now, let’s break down the above code:

• Here we are using the async function called fetchData.
• The data is being fetched from the https://api.coronavirus.data.gov.uk/v1/data API.
• The JSON data is stored in a variable called record.
• The HTML content of td with ids date, areaName, latestBy and deathNew are updated by the corresponding values of API.

If we check the browser, we will be able to see the following result.

Latest Covid Report of UK - Browser Preview

The data is being fetched from the API and it keeps on updating as soon as the data in API changes.

Manifest.json File

As we discussed earlier, building a Chrome extension is similar to building any web application. The only difference is that the Chrome extension requires a manifest.json file where we keep all the configurations.

The manifest.json file contains all the necessary information required to build the Chrome extension. It is the first file the extension checks and everything is loaded from this single file.

Now, let's create a manifest.json file in the root folder and add the following code:

{
    "name": "Covid-19 Stats UK",
    "version": "1.0.0",
    "description": "latest covid data of UK",
    "manifest_version": 3,
    "author": "Sampurna Chapagain",
    "action":{
        "default_popup": "index.html",
        "default_title": "Latest Covid Report"
    }
}

Our manifest.json file contains the value of name, version, description, manifest_version (3 in this case, which is the latest manifest version), author, and action fields. In the action field, there's the value for default_popup which contains the path to the HTML file which is index.html in this example.

You can have a look here to see all configurations of a manifest.json file.

Now, since we've also added the manifest.json file we are ready to add this project as an extension in our Chrome browser.

For that, we need to go to Select More Tools and then choose Extensions from the browser menu as shown in the picture below:

Navigating to extensions in Chrome

After choosing Extensions, it redirects to the extensions page in Chrome. Make sure to enable the Developer mode here.

Once that's done, you need to click the Load unpacked button which will allow us to load our project in the Chrome extension store.

Now, the extension is available in our Chrome extension store. You can also pin the extension in the browser as shown in the gif below:

Pin extension to the browser

This extension works only in your browser. If you want to publish it on the Chrome Web Store, you can follow this link.

Conclusion

If you have some HTML, CSS, and JavaScript knowledge, you can easily build Chrome extensions. I hope after reading this blog post, you will create some cool extensions.

Happy Coding!

You can find me on Twitter for daily content related to Web Development.

We will finish by actually writing our own extension (Super Fun!) which allows us to copy any code snippet to our clipboard with a click of a single button.

To continue with this article:

• You need to have a basic understanding of JavaScript.

• You need the Firefox browser (or any other browser will also work)

What is a Browser Extension?

A browser extension is something you add to your browser which enhances your browsing experience by extending the capacity of your browser.

As an example, think about an ad blocker which you might have installed on your device. This makes your browsing experience better by blocking ads when you surf the web.

How to Write Your Own Basic Browser Extension

Now let's start by writing a very basic extension.

To begin, we'll create a folder inside which we create a file named manifest.json.

What is a manifest file?

A manifest file is a must have file in any browser extension. This file contains basic data about our extension like name, version, and so on.

Now inside the manifest.json file copy the following snippet:

{
  "manifest_version":2,
  "version":"1.0",
  "name":"Test",
}

[2025 Update: Chrome currently only supports version 3 for manifest.json]

How to load the extension file

For Firefox users, follow these steps:

In the address bar, search for this:

about:debugging#/runtime/this-firefox

You will see an option to Load Temporary Add-on. Click on that option and choose the manifest.json file from the directory.

For Chrome users:

In the address bar search for this:

chrome://extensions

• Enable Developer Mode and switch into it.

• Click the Load unpacked button and select the extension directory.

Hurray! You've installed the extension successfully. But the extension doesn't do anything currently. Now let's add some functionality to our extension. To do this, we'll edit our manifest.json file like this:

{
  "manifest_version":2,
  "version":"1.0",
  "name":"Test",
  "content_scripts":[
    {
     "matches":["<all_urls>"],
     "js":["main.js"]
    }
  ]
}

In the above code, we added a content script to manifest.json. Content scripts can manipulate the Document Object Model of the web page. We can inject JS (and CSS) into a web page using a content script.

"matches" contains the list of domains and subdomains where the content script should be added and js is an array of the JS files to be loaded.

Now inside the same directory create a main.js file and add the following code:

alert("The test extension is up and running")

Now reload the extension and when you visit any URLs you will see an alert message.

Don't forget to reload the extension anytime you edit the code.

How to Customize Your Browser Extension

Now let's have some more fun with our extension.

What we are going to do now is create a web extension that changes all the images of a webpage we visit to an image we choose.

For this, just add any image to the current directory and change the main.js file to:

console.log("The extension is up and running");

var images = document.getElementsByTagName('img')

for (elt of images){
   elt.src = `${browser.runtime.getURL("pp.jpg")}`
   elt.alt = 'an alt text'
}

Let's see whats going on here:

var images = document.getElementsByTagName('img')

This line of code selects all the elements in the web page with the img tag .

Then we loop through the array images using a for loop where we change the src attribute of all the img elements to a URL with the help of the runtime.getURL function.

Here pp.jpg is the name of the image file in the current directory in my device.

We need to inform our content script about the pp.jpg file by editing the manifest.json file to:

{
  "manifest_version":2,
  "version":"1.0",
  "name":"Test",
  "content_scripts":[
   {
    "matches":["<all_urls>"],
    "js":["main.js"]
   }
  ],
  "web_accessible_resources": [
        "pp.jpg"
  ]
}

Then just reload the extension and visit any URL you like. Now you should see all the images being changed to the image which is in your current working directory.

How to add icons to your extension

Add the following code in the manifest.json file:

"icons": {
  "48": "icon-48.png",
  "96": "icon-96.png"
}

How to add a toolbar button to your extension

Now we'll add a button located in the toolbar of your browser. Users can interact with the extension using this button.

To add a toolbar button, add the following lines to the manifest.json file:

"browser_action":{
   "default_icon":{
     "19":"icon-19.png",
     "38":"icon-38.png"
   }
  }

All the image files should be present in your current directory.

Now, if we reload the extension we should see an icon for our extension in the toolbar of our browser.

How to add listening events for the toolbar button

Maybe we want to do something when a user clicks the button – let's say we want to open a new tab every time the button is clicked.

For this, we'll again add the following to the manifest.json file:

"background":{
        "scripts":["background.js"]
  },
  "permissions":[
      "tabs"
  ]

Then we'll create a new file named background.js in the current working directory and add the following lines in the file:

function openTab(){

    var newTab = browser.tabs.create({
        url:'https://twitter.com/abhilekh_gautam',
        active:true
    })
}

browser.browserAction.onClicked.addListener(openTab)

Now reload the extension!

Whenever someone clicks the button, it calls the openTab function which opens a new tab with the URL that links to my twitter profile. Also, the active key, when set to true, makes the newly created tab the current tab.

Note that you can use APIs provided by browsers in the background script. For more about APIs refer to the following article: Javacript APIs.

Now that we've learned some of the basics of browser extensions, let's create an extension that we as developers can use in our daily lives.

Final Project

Alright, now we're going to write something that will be useful for us in daily life. We'll create an extension that allows you to copy code snippets from StackOverflow with a single click. So our extension will add a Copy button to the webpage which copies the code to our clipboard.

Demo

First we'll create a new folder/directory, inside which we'll add a manifest.json file.

Add the following code to the file:

{
  "manifest_version":2,
  "version":"1.0",
  "name":"copy code",
  "content_scripts":[
    {
     "matches":["*://*.stackoverflow.com/*"],
     "js":["main.js"]
    }
  ]
}

Look at the matches inside the content script – the extension will only work for StackOverflow's domain and subdomain.

Now create another JavaScript file called main.js in the same directory and add the following lines of code:

var arr =document.getElementsByClassName("s-code-block")

for(let i = 0 ; i < arr.length ; i++){
 var btn = document.createElement("button")
 btn.classList.add("copy_code_button")
 btn.appendChild(document.createTextNode("Copy"))
 arr[i].appendChild(btn)
 //styling the button
 btn.style.position = "relative"

 if(arr[i].scrollWidth === arr[i].offsetWidth && arr[i].scrollHeight === arr[i].offsetHeight)
  btn.style.left = `${arr[i].offsetWidth - 70}px`

  else if(arr[i].scrollWidth != arr[i].offsetWidth && arr[i].scrollHeight === arr[i].offsetWidth)
   btn.style.left = `${arr[i].offsetWidth - 200}px`
 else 
   btn.style.left = `${arr[i].offsetWidth - 150}px`

 if(arr[i].scrollHeight === arr[i].offsetHeight)
   btn.style.bottom = `${arr[i].offsetHeight - 50}px`

 else
   btn.style.bottom = `${arr[i].scrollHeight - 50}px`
 //end of styling the button

   console.log("Appended")
}

First of all, I selected all the elements with the class name s-code-block – but why? This is because when I inspected StackOverflow's site I found that all the code snippets were kept in a class with that name.

And then we loop through all those elements and append a button in those elements. Finally, we just position and style the button properly (the styling's not perfect yet – this is just a start).

When we load the extension using the process we went through above and visit StackOverflow, we should see a copy button.

How to add functionality to the button

Now, when the button is clicked we want the entire snippet to be copied to our clip board. To do this, add the following line of code to the main.js file:

var button = document.querySelectorAll(".copy_code_button")
 button.forEach((elm)=>{
  elm.addEventListener('click',(e)=>{
    navigator.clipboard.writeText(elm.parentNode.childNodes[0].innerText)
    alert("Copied to Clipboard")
  })
 })

First of all, we select all the buttons we have added to the site using querySelectorAll. Then we listen for the click event whenever the button is clicked.

navigator.clipboard.writeText(elm.parentNode.childNodes[0].innerText)

The above line of code copies the code to our clipboard. Whenever a snippet is copied we alert the user with the message Copied to clipboard and we are done.

Final Words

Web Extensions can be useful in various way and I hope with the help of this article you will be able to write your own extensions.

All the code can be found in this GitHub repository. Don't forget to give a pull request anytime you come up with some good styling or a new feature like clipboard history and others.

Happy Coding!

In the world of web development, Chrome extensions are a pretty handy set of tools to have around.

Whether you use them to add headers to simple requests or to scrape important data from the DOM, extensions help provide extra functionality that makes life easier.

I started playing around with developing a Chrome extension for a use-case I had in mind at work. It was then that I stumbled upon the way we pass around certain data from a web page to an extension. And the lack of a simplified guide made me write this article.

We do have the Chrome API documentation, and it is indeed very thorough. But I consider myself to be more of a visual learner, and being able to visualize how we pass messages between the extension scripts helped simplify the overall development.

Note: This article makes use of Manifest V2 instead of V3. The major difference between the two is the usage of service workers in V3 instead of background pages and related actions.

Message Passing: Interaction Between Scripts

An extension, as the name suggests, is like a layer on top of the existing webpage you're trying to access. The browser acts as the container.

It mainly comprises the following scripts:

• Popup Script - Local JavaScript file for the extension DOM
• Background Script - Provides persistence and handles background events
• Content Script - Scripts that run in isolation in the context of the web page
• Injected Script - Scripts that are programmatically injected into the web page

Normally, if you have to merely deal with the DOM content, then the way the extension is developed is relatively straightforward.

The raw HTML is already available to the content script and all you need to do is pass it to the popup script.

However, if you need to access the page's variables and functions, the process gets a little tricky.

The variables and functions available in the page context, say in the window object, are not accessible to the content scripts since they tend to run in a special JavaScript environment. They have access to only the DOM of the page but not the variables and functions.

To access a page's variables and functions, we inject scripts by appending them to the DOM. This makes the browser assume that it is run in the context of the web page. This in turn provides the injected script access to the local variables and functions.

Since Chrome extensions are event-driven because of their architecture, once the injected scripts have access to the page's variables and functions, they can pass it to the content script.

The content script then passes the these objects to the background page.

And finally, the popup script is able to call onto the background page using the Extension API and pass it to the Extension DOM.

Message Passing Overview

Now, we will build a simple Performance Watcher extension that reads the performance data from the global window object of a page and maps the essential metrics for the user to see. Let's get into the code then.

Enough Talk, Show Me The Code

You can find the complete code repository for the project here. Let's quickly run through the primary files and the important functionalities they offer.

The Manifest File

Every Chrome Extension needs a manifest file. It is basically a JSON-formatted file that provides a set of metadata so the browser can recognize the permissions that need to be granted and the likely operational reach of the extension.

Here is the manifest used for our application.

manifest.json: metadata for your extension

Some of the important properties we need to focus on are the following:

• background - Takes an array of scripts that would be run in the background page.
• content-scripts - Includes an array of content scripts we wish to run as part of the web page's context.
• web_accessible_resources - An array of packaged resources expected to be used in a web page's context. For example, an image we intend to embed in a page or a custom script we want to inject.
• permissions - Allows your extension to gain access to certain Chrome APIs like tabs in this case.

The Content Script

Content Scripts have easy access to the DOM of the web page. We make use of the content script to append our custom script – inject-script.js – into the DOM.

content-script.js: inject custom script into the DOM

The content script also simultaneously continues to listen for any message being sent upstream from the custom script.

As soon as we get a message from the injected script, we run a quick check on the data received and verify whether our extension is installed. Once done, we simply use Chrome's Runtime API to send the data received forward to the background page.

content-script.js: send the required data to the background page

The Injected Script

The custom script can access global variables and functions like the window object. We map only the properties we require.

inject-script.js: procure required object from the page's JS context

The message from the custom script is communicated safely to the content script using the [window.postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) function. In this case, a setInterval function is used to dynamically update the properties we are observing.

inject-script.js: send the gathered data to the content-script

The Background Script

The background script listens for any message transmitted by the content script using the Runtime API. The window object of the background page is then updated with the tab.id acting as the identifier.

background.js: listen for incoming message from the content-script

The Popup Script

The popup script is where we finally read the data we had procured from our custom script. It is also the place where we code any necessary JavaScript operations.

The background page is retrieved using the getBackgroundPage method of the Extension API. The active tab's id is queried using the tabs.query method of the Tabs API in order to correctly extract the relevant data.

popup.js: reading the global object stored in the background page context

In this way, we are able to finally receive and map the data we need – performance in our case – efficiently in our extension.

The UI styling and other cosmetic code are available in the repository, for further reference.

Final Thoughts

Message passing is an essential concept when it comes to developing a Chrome extension. This is just one of the multiple ways in which you can communicate between scripts.

I spent a few hours in order to figure out how it would work for my use case. Hopefully, this simple walkthrough and the visual representation saves you some time.

I would suggest playing around with the code for a bit. If you have any questions, feel free to reach out to me on [LinkedIn](https://www.linkedin.com/in/tarique-ejaz/).

In the meantime, keep coding.

Building a Chrome extension can be overwhelming. It's different than building a web app in that you don't want to put too much JavaScript overhead on the browser since your extension will be run along with the website you're visiting. You also don't usually get the benefit of bundling and debugging that are available with today's bundlers and frameworks.

When I decided to build a Chrome extension, I found that the number of blog posts and articles about building one is quite small. And there's even less information when you want to use one of the newer technologies like TailwindCSS.

In this tutorial we will discover how to build a Chrome extension using Parcel.js for bundling and watching and TailwindCSS for styling. We will also talk about how to separate your styling from the website to avoid colliding CSS – but more on that later.

There are a few types of Chrome extensions worth mentioning:

• Content scripts: The first type of Chrome extension is the most common. It runs in the context of a web page and can be used to modify its content. This is the type of extension we'll be creating.
• Popup: Popup-based extensions use the extension icon to the right of the address bar to open a popup which can contain any HTML content that you like.
• Options UI: You guessed it! This is a UI for customizing options as an extension. It's accessible by right clicking the extension icon and selecting "options" or by navigating to the extension's page from the Chrome extensions list chrome://extensions
• DevTools Extension: "A DevTools extension adds functionality to the Chrome DevTools. It can add new UI panels and sidebars, interact with the inspected page, get information about network requests, and more". -Google Chrome documentation

In this tutorial we will build a Chrome extension using only content scripts by displaying content on the web page and interacting with the DOM.

How to bundle your Chrome Extension using Parcel.js V2

Parcel.js is a zero-configuration web application bundler. It can use any kind of file as an entry point. It's simple to use and will work for any type of app including Chrome Extensions.

First create a new folder called demo-extension (make sure you have yarn or npm installed, I am going to use yarn for this post):

$ mkdir demo-extension && cd demo-extension && yarn init -y

Next we will install Parcel as a local dependency:

$ yarn add -D parcel@next

Now create a new directory called src:

$ mkdir src

Adding a manifest file

Every browser extension needs a manifest file. This is where we define the version and meta data about our extension, but also the scripts that are used (content, background, popup, .etc) and permissions if any.

You can find the full schema in Chrome's documentation: https://developer.chrome.com/extensions/manifest

Let's go ahead and add a new file in src called manifest.json with this content:

{
  "name": "Demo extension",
  "description": "An extension built with Parcel and TailwindCSS.",
  "version": "1.0",
  "manifest_version": 2,
}

Now, before we go into more detail about how chrome extensions work and the kind of stuff you can make with them, we are going to set up TailwindCSS

How to use TailwindCSS with your Chrome Extension

TailwindCSS is a CSS-framework that uses lower-level utility classes to create reusable but also customizable visual UI components.

Tailwind can be installed in two ways, but the most common way to use it is via its NPM package:

$ yarn add tailwindcss

Also, go ahead and add autoprefixer and postcss-import:

$ yarn add -D autoprefixer postcss-import

You need these to add vendor prefixes to your styles and to be able to write syntax like @import "tailwindcss/base" to import Tailwind files directly from node_modules, respectively.

Now that we have it installed, let's make a new file inside our root directory and call it postcss.config.js. This is the configuration file for PostCSS and it will contain, for now, these lines:

module.exports = {
  plugins: [
    require("postcss-import"),
    require("tailwindcss"),
    require("autoprefixer"),
  ],
};

Order of plugins matters here!

That's it! That's all you need to get started using TailwindCSS within your Chrome extension.

Create a file called style.css inside your src folder and include Tailwind files:

@import "tailwindcss/base";
@import "tailwindcss/utilities";

Remove unused CSS using PurgeCSS

Let's also make sure we only import the styles we use by enabling Tailwind's purging capability.

Create a new Tailwind configuration file by running:

$ npx tailwindcss init: this will create a new tailwind.config.js file.

To remove unused CSS, we're going to add our source files to the purge field like this:

module.exports = {
  purge: [
    './src/**/*.js', 👈
  ],
  theme: {},
  variants: {},
  plugins: [],
}

Now our CSS will be purged and unused styles will be removed when you build for production.

How to enable Hot Reloading within your Chrome Extension

One more thing before adding some content to our extension: let's enable hot reloading.

Chrome doesn't reload the source files when you make new changes – you need to hit the "Reload" button on the extensions page. Fortunately, there's an NPM package that does hot reloading for us.

$ yarn add crx-hotreload

In order to use it, we'll create a new file called background.js inside our src folder and import crx-hotreload

import "crx-hotreload";

Finally point to background.js in manifest.json so it can be served with our extension (hot reloading is disabled in production by default):

{
  "name": "Demo extension",
  "description": "An extension built with Parcel and TailwindCSS.",
  "version": "1.0",
  "manifest_version": 2,
  "background": { 👈
    "scripts": ["background.js"]
  },
}

Enough with configuration. Let's build a small script form within our extension.

Types of scripts in a Chrome extension

As mentioned in the beginning of this post, in Chrome extensions there a few types of scripts you can use.

Content scripts are scripts that run in the context of the visited web page. You can run any JavaScript code that is otherwise available in any regular web page (including accessing/manipulating the DOM).

A background script, on the other hand, is where you can react to browser events, and it has access to the Chrome extension APIs.

Adding a content script

Create a new file called content-script.js under the src folder.

Let's add this HTML form to our newly created file:

import cssText from "bundle-text:../dist/style.css";

const html =
`
<style>${cssText}</style>

<section id="popup" class="font-sans text-black z-50 w-full fixed top-0 right-0 shadow-xl new-event-form bg-white max-w-sm border-2 border-black p-5 rounded-lg border-b-6">
  <header class="flex mb-5 pl-1 items-center justify-between">
    <span class="text-2xl text-black font-extrabold">New event!</span>
  </header>
  <main class="event-name-input mb-6">
    <div class="mb-6">
      <label
        for="event-name"
        class="font-bold pl-1 block mb-1 text-black text-xl"
        >
      Event name
      </label>
      <div class="duration-400 flex bg-white border-black border-2 rounded-lg py-4 px-4 text-black text-xl focus-within:shadow-outline">
        <input
          id="event-name"
          name="event-name"
          type="text"
          placeholder="web.dev LIVE"
          class="font-medium w-full focus:outline-none"
          />
      </div>
    </div>
    </div>
    <div class="mb-6">
      <label
        for="event-date"
        class="font-bold pl-1 block mb-1 text-black text-xl"
        >
      Date
      </label>
      <div class="event-date-input duration-400 border-black flex bg-white border-2 rounded-lg py-4 px-4  text-xl focus-within:shadow-outline">
        <input
          id="event-date"
          name="event-date"
          type="date"
          class="font-medium w-full focus:outline-none"
          />
      </div>
    </div>
    <div class=" mb-8">
    <label
      for="event-time-input"
      class="font-bold pl-1 block mb-1  text-xl"
      >
    Time
    </label>
    <div class="inline-flex items-center">
      <input
        id="event-time-input"
        type="time"
        value="17:30"
        class="border-black mr-4 lowercase duration-400 w-auto bg-white text-xl border-2  rounded-lg px-4 py-4 focus:outline-none focus:shadow-outline"
        />
      <div class="inline-flex flex-col">
        <span class="text-xl font-bold">Casablanca</span>
        <span class="text-base font-normal">Africa</span>
      </div>
    </div>
  </main>
  <footer>
  <button 
    class="duration-400 bg-green-400 text-xl py-4 w-full rounded-lg border-2 border-b-6 leading-7 font-extrabold border-black focus:outline-none focus:shadow-outline"
    >
  Save
  </button>
  </footer
</section>
`

const shadowHost = document.createElement("div");
document.body.insertAdjacentElement("beforebegin", shadowHost);
const shadowRoot = shadowHost.attachShadow({ mode: 'open' });

shadowRoot.innerHTML = html

Styling a browser extension is not as straightforward as you may think because you need to make sure that the website styles are not affected by your own styles.

In order to separate them, we are going to use something called the Shadow DOM. The Shadow DOM is a powerful encapsulation technique for styles. This means that styling is scoped to the Shadow tree. Therefore, nothing is leaked out to the visited web page. Also outside styles do not override the Shadow DOM's content, although CSS variables can still be accessible.

A shadow host is any DOM element we would like to attach our Shadow tree to. A Shadow Root is what is returned from attachShadow and its content is what gets rendered.

Beware, the only way to style the content of a Shadow tree is by inlining styles. Parcel V2 has a new built-in feature where you can import the content of one bundle, and use it as compiled text inside your JavaScript files. Then Parcel will replace it at the time of packaging.

We did exactly that with our style.css bundle. Now we can inline the CSS automatically to the Shadow DOM at build time.

Now we have to tell the browser about this new file, let's go ahead and include it by adding these lines to our manifest:

{
  "name": "Demo extension",
  "description": "An extension built with Parcel and TailwindCSS.",
  "version": "1.0",
  "manifest_version": 2,
  "background": {
    "scripts": ["background.js"]
  },
  👇
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content-script.js"],
    }
  ]
}

In order to serve our extension, we are going to add a few scripts to our package.json:

  "scripts": {
    "prebuild": "rm -rf dist .cache .parcel-cache",
    "build:tailwind": "tailwindcss build src/style.css -c ./tailwind.config.js -o dist/style.css",
    "watch": "NODE_ENV=development yarn build:tailwind && cp src/manifest.json dist/ && parcel watch --no-hmr src/{background.js,content-script.js}",
    "build": "NODE_ENV=production yarn build:tailwind && cp src/manifest.json dist/ && parcel build src/{background.js,content-script.js}",
  }

Finally you can run yarn watch, go to chrome://extensions, and make sure Developer Mode is enabled on the top right of the page. Click on "Load Unpacked" and select the dist folder under demo-extension.

• If you get this error: Error: Bundles must have unique filePaths you can simply fix it by removing the main field in your package.json

How to publish your extension to the Google Chrome Web Store

Before going further into this, let's add a new NPM script that will help us compress the extension files as required by Chrome.

  "scripts": {
    "prebuild": "rm -rf dist .cache",
    "build:tailwind": "tailwindcss build src/style.css -c ./tailwind.config.js -o dist/style.css",
    "watch": "NODE_ENV=development yarn build:tailwind && cp src/manifest.json dist/ && parcel watch --no-hmr src/{background.js,content-script.js}",
    "build": "NODE_ENV=production yarn build:tailwind && cp src/manifest.json dist/ && parcel build src/{background.js,content-script.js}",
    "zip": "zip -r chrome-extension.zip ./dist" 👈
  }

If you haven't installed zip yet, please do so:

• MacOS: brew install zip
• Linux: sudo apt install zip
• For Windows, you can use the powershell command Compress-Archive similarly: powershell Compress-Archive -Path .\\dist\\ -Destination .\\chrome-extension.zip

Now all you have to do is head to Chrome Web Store Developer Dashboard to set up your account and publish your extension ?

• You can find the complete demo for this tutorial hosted on my GitHub account here

Conclusion

In the end, Chrome extensions are not that different from web apps. Today you learned how to develop an extension using the latest technologies and practices in web development.

Hopefully this tutorial helped you speed up your extension development a little bit!

If you found this helpful, please Tweet about it and follow me at @marouanerassili.

Thank you!

We may need to go and search for an online tool that turns it into an easy-to-read format so we can understand it.

Now, here is a Chrome and Firefox extension that does the formatting and makes your JSONs instantly pretty inside your browser, without having to perform many unnecessary steps.

It comes with support for JSON and JSONP and highlights the syntax so that you can differentiate different attributes and values accordingly. It also comes with the option to collapse nodes, clickable URLs that you can open in new tabs, and you see the raw, unformatted JSON.

It works with any JSON page, regardless of the URL you opened. It also works with local files, after you enable it in chrome://extensions. You can inspect the JSON by typing json into the console.

You can install the extension by going here for Chrome and here for Firefox and then test it, for example, by visiting this API response.

This is what it looks like, before formatting:

Now, take a look at the beautiful JSON response you get with JSON Formatter:

Here is a pro tip: Hold down CTRL (or CMD on Mac) while collapsing a tree, if you want to collapse all its siblings too.

It is an open-source project, so you can view its source code on GitHub.

Thanks for reading.

Every Chrome extension is published on the Chrome Web Store. Think of it as the equivalent to Google’s Play Store or Apple’s App Store, but only for Chrome extensions and themes.

Steps

If you haven’t created one already, you will need to create a Developer account. In it, you will have a Developer Dashboard.

As I stated in the previous article, there is a $5 one time signup fee if you want to be able to publish Chrome extensions. This will give you the ability to publish up to 20 extensions

Once you are the proud owner of a Developer account, the next step is to upload your Chrome extension to your account. To do this, create a ZIP file with all the files associated with your extension. The only file Google requires you to upload is the manifest.json file. But you will want to add the JavaScript files you have as well.

After that, the next step is to publish our extension. Login to your developer account and go to your Developer Dashboard.

There you will see an Add New Item button.

Click Me

⚠️ Be aware that once you add an extension to your Developer Dashboard you cannot delete it. As long as it is not published, it will not count towards your extension limit.

This will direct you to a page where you can upload the ZIP file we created earlier:

Click choose file and press upload

Assuming everything went fine, you will be directed to the next page:

Here you can provide a description of your extension

If you are planning to make changes to your extension, you can use the Upload Updated Package button to re-upload your ZIP file.

On this page, you can add an icon that will be shown on the toolbar:

Add screenshots of your extension (these will be used when a user looks at your extension):

And various other features like choosing a Category for the extension (I.E. Fun), choosing the regions where your extension will be available, the pricing of your extension, and other categories which I suggest you take a look at.

When you are done fine tuning the details of your extension, you will arrive at the end of the page and see the following buttons:

The two left buttons allow you to save the work you have done so far configuring your extension (or discarding it), and the two right ones are for when you are ready to publish. To see how everything you configured will look on the Chrome Web Store, press the Preview Changes button. When you are satisfied with what you have, click Publish Changes.

_Photo by [Unsplash](https://unsplash.com/@adspedia?utm_source=medium&utm_medium=referral" rel="noopener" target="_blank" title="">Val Vesa on <a href="https://unsplash.com?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

Congratulations! You have just published your first Chrome Extension!

In your Developer Dashboard you will now see this:

Clicking the Stats link will give you analytics regarding your extension (how many impressions, installs and active users). I’m looking forward to seeing your published Chrome extensions.

In this article, I’ll explain the building blocks of a Chrome extension. Afterwards, you’ll just have to think of a good idea as an excuse to make one.

Why Chrome?

Chrome is by far the most popular web browser. Some estimations are as high as 59%. So, if you want to reach as many people as you can, developing a Chrome extension is the best way to do it.

⚠️ To be able to publish a Chrome extension, you need to have a developer account which entails a $5 one-time signup fee.

Each Chrome extension should have these components: the manifest file, popup.html and popup.js and a background script. Lets take a look at them.

What makes up a Chrome extension?

The Manifest File

What is a manifest file? It is a text file in JSON (JavaScript Object Notation) format that contains certain details about the extension you will be developing.

Google uses this file to acquire details about your extension when you will publish it. There are required, recommended and optional fields.

Required

{
  "manifest_version": 2,
  "name": "My Chrome Extension",
  "version": "1.0",
  "default_locale": "en"
}

• manifest_version - Version of the manifest file format. As of Chrome 18, version 1 is deprecated
• name - Can be up to 45 characters. Used to display your extension’s name in the following places: Install dialog, Extension management UI, Chrome Web Store
• version - Version of your Chrome Extension. Can be up to four digits separated by dots (e.g., 1.0.0.0)
• default_locale - This folder resides inside the _locals folder and it contains the default string literals. The _locals folder is used for internationalization (allowing your extension to support multiple languages). It is a required field if a _locals folder exists, otherwise, it should not be present

If you want to support multiple languages, read more here.

Recommended

  "description": "A plain text description",
  "author": "Your Name Here",
  "short_name": "shortName",
  "icons": {
      "128":"icon128.png",
       "48":"icon48.png",
       "16":"icon16.png"
    },

• description - You can use up to 132 characters to describe the extension
• short_name - Limited to 12 characters, it is used in cases where there is not enough space to display the full name of the extension (App Launcher and New Tab Page)
• icons - The icons that represent the extension. Always include a 128X128 icon because it is used by the Chrome Web Store and during the installation of your extension

Optional fields are case specific, so we won’t go into them in this article.

After covering the data needed for the manifest file, we can now move on to where we will actually be writing code for our extension, Popup and Background.

Popup and Background

The popup refers to the main page users see when using your extension. It consists of two files: Popup.html and a JavaScript file, Popup.js.

Popup.html is the layout file for how your extension will look like. Depending on what your extension will do, the markup of this file will change.

A background script is the only one that can interact with events that occur and use the Chrome API. To use background scripts you need to add the following to your manifest.json file:

{
  "manifest_version": 2,
  "name": "My Chrome Extension",
  "version": "1.0",
  "background":{
        "scripts": ["yourScript.js"],
        "persistent": false
    }
}

The key scripts has a value of an array of script names.

persistent is a key with a boolean value which denotes the use of your extension with chrome.webRequest API to block or modify network requests. The Chrome.webRequest API does not work with non-persistent background pages.

_“open signage on door” by [Unsplash](https://unsplash.com/@belart84?utm_source=medium&utm_medium=referral" rel="noopener" target="_blank" title="">Artem Bali on <a href="https://unsplash.com?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

How Your Extension Will Open

Every Chrome extension adds a little icon to the toolbar at the top of your browser. Once the user clicks that icon, you can choose how you want your extension to open in the browser:

1. It can override a new tab, so as not to disrupt the current user’s activity

2. You can open a small window in the user’s current tab, so as to keep the user in the same tab

Each choice has it’s consequences and it is up to you to decide what is the best option for you.

Below is the code needed to pull off each of the options. They will both use the same popup.html file outlined below:

<html>

    <head>

        <title>Chrome Extension Example</title>
    </head>

    <body>

        <h1>Hello From Extension</h1>

    </body>


</html>

Putting It All Together

Override New Tab

//In manifest.json
{
    "name": "ChromeExampleNewTab",
    "version": "1.0",
    "manifest_version": 2,
    "chrome_url_overrides": {
        "newtab": "popup.html"
    },
    "browser_action": {}, 
    "permissions":[        
        "tabs"
    ],
    "background":{        
        "scripts": ["background.js"],
        "persistent": false
    }
}

//In background.js
chrome.browserAction.onClicked.addListener(function(tab) {
    chrome.tabs.create({'url': chrome.extension.getURL('popup.html')}, function(tab) {
        // Tab opened.
    });
});

Open In The Current Tab

//In manifest.js
{
    "name": "ChromeExample",
    "version": "1.0",
    "manifest_version": 2,
    "browser_action": {         
      "default_popup": "popup.html"
    }
}

Notice how we have overridden the browser_action key in both examples.

We have to do this, since we don’t want the browser to open a new tab in the regular fashion.

Also, since if we want to open a new tab with our extension, we must add a permissions key to the manifest and specify the tabs value. This lets the browser know we need the user’s permission to overwrite the default behavior of opening a new tab.

There is a whole lot more to Chrome extensions (messaging, context menus and storage to name a few). I have hopefully given you some insight into Chrome extensions. Maybe just enough to intrigue you to make one of your own!

And while you are at it, check one I have made here.

Yeah, the title, I know… but I had to try it at least once in my life ??

For many of us, Medium is the go-to platform for writing and publishing content online. It provides an extremely slick writing experience and, to be honest, I can’t imagine using anything else anymore…

I have been using Medium for years and I was always curious about the total reach of my articles

Unfortunately, Medium stats can be described only as very basic or, to be frank, utterly lacking in the feature department. Even simple stuff like a summary row with a total count of the views and reads at the bottom of the table is missing.

The only solution is to add the numbers manually which is a boring, error-prone process. It gets progressively more tedious with the increasing number of articles, so you basically get punished for being a productive writer…

But hey, there is hope…

…at least for the people using Google Chrome and Opera with this amazing Opera addon and then installing standard Chrome extension.

Introducing Medium Enhanced Stats

What is in it for You? ????

To put it briefly, there are four main features of Medium Enhanced Stats:

1. Total reach indicator
2. Bar chart article markers
3. Stats table summary row and extra information
4. Support for users and publications
5. ? An Easter Egg to be found, if you’re not afraid to roll up your sleeves and explore the source ???

Add Medium Enhanced Stats to your Google Chrome now! Yes, it’s 100% FREE!

Or to Opera with this amazing Install Chrome Extensions addon.

Total reach indicator

Total reach is a sum of all the views of your articles and responses.

Instead of being a plain number, indicator contains a next milestone and a progress bar which shows how much you have already accomplished.

Milestone is calculated as a next 10x “round” number.

For example, people with a reach under 1K will achieve their 1K milestone pretty quick, but it will probably take more time to move from 1M to 10M…

Then again, I would be very happy if you proved my assumption wrong ?

I would like to thank Johann Gyger for his help with debugging the extension popup! ??????

Bar chart article markers

Have you ever caught yourself wondering what was the cause of that pronounced views bump 3 months ago? Me too! Luckily the newest feature of Medium Enhanced Stats set out to solve just that…

Check out article markers in the bar chart and discover effect of their publishing on the overall performance…

Medium’s original bar chart is now enhanced with the article markers. It also works for responses and can handle displaying multiple articles per day.

Markers can handle also multiple articles per day and the marker size reflects amount of articles… Yes, bigger IS better ?

Summary row and extra information

This was the initial feature of the extension, and was basically the way it all started out: having a simple summary row which displays the sum of the values per column.

You know, Excel sum ∑ stuff…

As it turned out, the retrieved data also contains the amount of claps per article. This is nowadays a much more useful metric, since Medium switched to displaying claps also in the UI of the articles themselves.

Summary row is exactly what it sound it is ? Besides that, there is also an additional claps column for every article…

Support for users and publications

In the beginning, Medium Enhanced Stats could only display stats for a single currently logged in author. Feedback from the first users came pretty fast: they were asking for the ability to do the same for their publications.

Just installed a new chrome extension http://goo.gl/XBvNFu by @tomastrajan. Very convenient. It says I’ve reached more than 1 million people! And it now encourages me to aim for 10 millions :). Great work, @tomastrajan! Can it show stats for a publication? — Max NgWizard K

Ask and you shall be given!

Click on the user avatar and select from available users and publications

Technical background for my fellow developers

Medium Enhanced Stats is a Chrome Extension. Chrome Extensions are great for enriching existing websites with custom functionality, because we have the possibility to inject custom scripts in a safe way.

Custom script can access and leverage all the visible and invisible data available on the original page. More so, because they now belong to the original site, they can also make requests on its behalf. And let me tell you, it is much easier to calculate totals from JSON data than to scrape an HTML table.

I am planning to write another post which will get much more into details of how to implement Chrome extensions so stay tuned…

FUN FACT — Medium Enhanced Stats retrieves and show total stats, right? Well, it’s almost total: you might need to worry if you’ve published more than 100k articles, which is currently the limit of the paging request ?

Before I forget, Medium Enhanced Stats is also fully open sourced on GitHub, so feel free to check it out. There is virtually no documentation available yet, but I will definitely add more in the future to enable community-driven efforts!

Future

Since its inception, the extension has already gone through a couple of major iterations and improvements.

Currently, there is a plan to try to visualise articles which are the major contributors to views each day. It can get rather tricky in situations with lots of articles with small individual contributions. It will be important to strike a good balance to make it useful instead of distracting.

Another opportunity worth exploring is adding a way to download and share a stylized total reach indicator with author’s name, Medium username, and other social media handles. This could be useful because authors would gain an easy way to communicate their contribution as a proxy of their trustworthiness for new members of their communities.

This is the end!

I hope you will try Medium Enhanced Stats out and let me know about your experience and possible enhancement ideas!

Please, help spread this article to a wider audience with your ? ? ? and follow me on ?️ Twitter to get notified about my newest blog posts ?

And never forget, the future is bright.

_Obviously the bright future (? by S[asha • Stories)](https://unsplash.com/@sanfrancisco" rel="noopener" target="blank" title=")

If you made it this far, feel free to check out some of my other articles about frontend software development…

How To Stay Up To Date With Releases Of Popular Frameworks
_Introducing Release Butler — A Twitter Bot That Helps You To Stay Up To Date With Releases Of Popular Frontend…_medium.comHow To Build Responsive Layouts With Bootstrap 4 and Angular 6 ?
E_very web app is assumed to be responsive, period.m_edium.com How To Speed Up Continuous Integration Build With New NPM CI And package-lock.json
_While very controversial, the new npm release 5.7.0 brings some amazing features which will have noticeable positive…_medium.com

Don’t forget ! ?

Basically, if I have no intention of using a service then I won’t bother reverse-engineering it. — Jon Lech Johansen

As evident from my bio, I am crazy about music and pretty much anything related to it. And I believe that music videos, if well-directed, are possibly the best way to feel the inherent soul of music.

So, it all began with me watching the music video of a song “Heavydirtysoul” by Twenty One Pilots. The music video was so dope I didn’t even care for the lyrics. It was only after I listened to it a few times, I realized that I didn’t get much of the lyrics except the chorus part.

This is something that is an actual problem for many ESL (English as a Second Language) speakers. You can’t enjoy a song to its fullest if you don’t get the lyrics.

It was then that I thought of something: what if I could play the lyrics of a song alongside the music videos (much like subtitles)? It would be awesome if I could create subtitle files for my music videos and then play it on my video player!

Initial Approach and finding Musixmatch

I then began a comprehensive search for sites or APIs that could provide me the lyrics for a song. And as expected, I found a dozen sites that provided the lyrics. Cool… isn’t it?

Nah. Because, what I really needed was timed lyrics, much like a subtitle for a movie. I wanted the lyrics text to sync with the current video frame on the screen. After much searching, I was unable to find any such service.

It was only after a week someone told me to use Musixmatch, a chrome extension that embedded lyrics on YouTube videos. So, yeah, there was someone out there who was already doing what I had thought about. It sounded like most of the other well thought so-called new ideas I had...and I was just a step away from fetching SubRip “srt” subtitle files for my favorite music videos.

And the hacking started…

I already had a bit of experience working with the chrome developer tools (thanks to Node.js and front end designing). So I put on my hacker glasses and fired up Chrome Dev tools. I switched to the network tab and began to look for any text file that could contain the lyrics.

Snapshot of developer tools with YouTtube video playing

But I was analyzing requests on a page that was playing YouTube videos, so I had a plenty of requests. And since the extension was fetching lyrics, the request must have something to do with the Musixmatch domain.

So I filtered using the keyword ‘musix’ and looked patiently for my file and I finally found it. Lyrics along with the time stamp. I noted the URL of that request and frankly, it all seemed like gibberish to me. Anyways, I copied the URL string as such and then pasted it into the URL bar, and voilà, I got the lyrics.

So, the only thing left was to find out how the URL is being framed and what were the parameters..

Request URL

Parameters and what?

After all the analyzing and filtering, I finally ended up with this. A long URL with a bunch of unknown parameters.

Parameters for the URL

I needed to dig deeper to actually understand the importance of each parameter. At a glance, it was clear that the only parameters that actually mattered were res and v. Others were just for house-keeping stuff. Then I began to explore the options and ended up wasting an hour just to find that the parameter v is nothing but the YouTube Video Id.

For example, the Video Id or v for a YouTube video with a URL https://www.youtube.com/watch?v=ZQeq_T_2VE8 is ZQeq_T_2VE8. Now that I had unveiled the mystery of v, I thought it would take me hardly another hour to find about res, but boy was I wrong.

The curious case of the parameter ‘res’

An hour of deep analysis and research gave me nothing. A little later, I realized that the URL worked even when I changed few alphabets. I kept up digging and by the end of the 3 hours, I figured out that the alphabets in the string didn’t mean anything. They were just put randomly.

A typical value of res : 90rt120b114xz70xv82w85vv90a94hn90vb102av86

So I was done with the alphabets but the numeric values were still alien to me. The next thing I could think of was applying a bit of reverse-engineering to analyze the numbers.

I began with removing all the alphabets as they didn’t mean anything and the first thing I noticed that the number of those values were fixed, the number being 11. I tried it with many other videos, but the number remained constant.

Suddenly, it struck me, Video Id, the v, we discussed earlier also had 11 characters. However, each character in v could be an alphabet or a digit or even a ‘-’ or ‘_’, unlike res which had only numbers.

So, I tried the most obvious mapping that can map a character to its numeric value, ASCII, and voilà that was it. The characters were ASCII encoded and alphabets were randomly put in between the numbers to make the whole string look more random, I guess.

At this point, I was delighted. After all, I had learned about all the parameters and was only a step away from writing my own handy script to download the lyrics file in “srt” format. Just to be sure, I checked with different videos and there seemed to be no issue whatsoever. I also shared the URL with one of my friends (yeah, a music lover).

I got a quick reply and it said “What is it? There’s nothing”. I crosschecked the URL and it was working fine on my browser.

Who was the culprit ? :P

I don’t get sent anything strange like underwear. I get sent cookies. :P — Jennifer Aniston

Cookie field in the Request Headers

I fired up the developer tools again and then copied the link for a new song. It again worked and then I switched to an incognito tab and pasted that same URL. It didn’t work.

My experience of CTF (Capture The Flag) contests immediately told me that it had something to do with the cookies. That’s the most likely case if a URL is working in a browser window and not the other.

I switched to the developer console and saw that the cookie was indeed being sent by the browser. To be sure, I analyzed the request many times and it finally occurred to me that the cookie being sent was the same the Musixmatch server is sending in the response. Also, each cookie is valid for only a certain time period.

So, I wrote a Python script using urllib that first gets the cookie from a normal HTTP response since the cookie works across the domain. Then the cookie along with other parameters was framed as an HTTP request and we got the lyrics... Finally!!

Preparing the parameters for a successful request

Here is the Python code for all the steps discussed above. The code first generates the parameters followed by a request to get the cookies. URL is then prepared using the parameters. Next, the cookie is defined in the header request along with other header fields like ‘Host’ and ‘User-agent’ to give it more of an authentic request look.

Parsing the raw timed lyrics into srt format

Now, the next major thing or the only task left was to convert the raw timed lyrics data into a proper srt (SubRip Text) format. Here is what the MusixMatch lyrics format looked like.

HTTP Response for the lyrics

Below is a proper format for a srt file.These files contain formatted lines of plain text in groups separated by a blank line. Subtitles are numbered sequentially, starting at 1 as depicted in the figure below.

100:00:00,350 --> 00:00:03,45071 buildings explodedor caught fire.

200:00:03,490 --> 00:00:05,020Elliot, tell me what it isthat you think he did.

300:00:05,060 --> 00:00:06,930Sorry.I don't know if I can say.

This sounded like a whole lot of work was required as the data was yet to be properly formatted. But, if you have the required data and a knowledge of Python, all it takes is a simple script to handle the data and that’s exactly what I did. The HTML tags annoyed me a bit during HTML parsing but guess what, there is an awesome library just for HTML parsing which made the whole process very easy. No points for guessing the library’s name, HTMLParser :-).

Final words

So, I put together this script along with some modifications and with a simple front end on a flask server, I had my own lyrics fetching interface, possibly the only one of its kind in the whole world !!

By the way, if you are into music, have a look at Musixmatch. It is really awesome. This exercise was just for educational purposes and wasn’t used in any way to violate Musixmatch’s copyright.