DEV Community: M.Bilal Khan

How MV3 Service Workers Made Me Use an Offscreen Document Just to Play a Goat Sound

M.Bilal Khan — Tue, 21 Jul 2026 06:59:27 +0000

So I built a Chrome extension that does one very stupid thing: it waits a random amount of time, then screams at you like a goat if you don't dismiss the notification fast enough.

Simple idea. Should've been a simple build. It was not, because Manifest V3 said no.

The plan was easy, in my head

Here's what I thought I needed:

chrome.alarms to fire at a random interval
chrome.notifications to show a "you good?" popup
If the user ignores it for 60 seconds, play a goat sound

Step 3 is where things fell apart. Because in Manifest V3, your background script isn't a persistent background page anymore — it's a service worker. And service workers have the audio capabilities of a rock. No Audio() object. No Web Audio API. Nothing. You can't just do new Audio('goat.mp3').play() and call it a day, because there's no DOM for it to live in.

I found this out the way everyone finds out things in MV3: by writing the obvious code, watching it silently fail, and then spending 20 minutes wondering if I'd misspelled "goat."

Enter: the offscreen document

Chrome's answer to "service workers can't do X" for a bunch of X's (audio playback included) is the offscreen document API. It's exactly what it sounds like — a hidden HTML page that exists purely so your extension has something with a DOM, so it can do DOM things. In my case, playing an mp3 of a goat losing its mind.

The flow ends up looking like this:

service worker (background.js)
  → creates an offscreen document if one doesn't exist
  → sends it a message: "play the sound"
offscreen.html/offscreen.js
  → has an <audio> tag
  → actually plays the sound
  → closes itself when done

It's a little bit like hiring a stunt double because the main actor (your service worker) isn't allowed near water. The offscreen document does the wet work, then goes home.

Rough version of what that looks like in code:

// background.js
async function playGoatSound() {
  if (!(await chrome.offscreen.hasDocument())) {
    await chrome.offscreen.createDocument({
      url: 'offscreen.html',
      reasons: ['AUDIO_PLAYBACK'],
      justification: 'Playing a goat scream sound effect'
    });
  }
  chrome.runtime.sendMessage({ action: 'playSound' });
}

// offscreen.js
chrome.runtime.onMessage.addListener((msg) => {
  if (msg.action === 'playSound') {
    const audio = new Audio('sounds/goat.mp3');
    audio.play();
  }
});

Nothing exotic. But it took me embarrassingly long to figure out that "reasons: ['AUDIO_PLAYBACK']" is a required field and not optional flavor text, and that you genuinely cannot skip the offscreen document if you want sound out of a service worker. There's no secret shortcut.

The other MV3 gotcha: your background script forgets everything

Service workers also don't persist. Chrome can (and will) kill your background script whenever it feels like, which is a problem when your whole app is "wait N minutes, then do a thing." If your script gets shut down mid-wait, a regular setTimeout just... doesn't fire. It's gone. Chrome ate it.

This is what chrome.alarms is actually for — it's not just a nice API, it's the only way to reliably schedule something in the future when your background context can disappear at any moment. So Goat Alert ends up using two alarms:

One for "time to show the notification" (the random 5/10/15/20 min interval)
One for "15 seconds have passed, did they dismiss it? No? Ok, scream."

Both survive the service worker dying and waking back up, because chrome.alarms is backed by the browser itself, not by whatever fragile JS context happened to be running when you set the timer.

What I'd tell past me

Building this taught me that a huge chunk of "why is my simple Chrome extension so complicated" comes down to one thing: Manifest V3 assumes your background script is disposable, and designs everything around surviving that. Once you accept that and stop trying to keep long-lived state or objects (like an Audio instance) alive in the service worker, the actual APIs make sense. Offscreen documents for anything DOM-shaped, alarms for anything time-shaped.

Anyway. 100+ installs, people are enjoying it, so all efforts are worth it.

Give it a try, will put a smile on your face Goat Alert

I spent a week trying to intercept Slack push notifications from a Chrome extension. Here's why it's impossible.

M.Bilal Khan — Wed, 15 Jul 2026 18:55:52 +0000

After I published my last article about building a Chrome extension that speaks browser notifications aloud, a commenter asked a question I didn't have a good answer to.

He pointed out that a lot of web apps — Slack, Gmail, most modern tools — fire their notifications from a service worker via registration.showNotification(), not from the page's JavaScript context. My MAIN world override of window.Notification would never reach those.

He was right. And I told him I'd look into it.

I spent a week researching whether there was any way to close that gap. There isn't. But the reason why is more interesting than a simple "no."

Two ways a website can show you a notification

When a website sends you a browser notification, it can do it in one of two ways.

The first is the constructor path. The page's own JavaScript calls new Notification("You have a message") directly. This is common for in-tab alerts, real-time updates when you're actively on the site, or any notification triggered by something you just did.

The second is the push path. The browser receives a push event from the website's server, wakes up the website's service worker in the background, and the service worker calls self.registration.showNotification() from inside its own scope. This is what happens when Slack notifies you of a new message while the tab is closed or backgrounded. The page never runs. No page JavaScript ever fires.

My extension catches the first path. The MAIN world content script overrides window.Notification before any page code runs. But the service worker never touches the page's window. It has no window. It runs in a completely isolated thread, completely separate from the page, and calls showNotification on itself.

The override is never reached.

Why can't the extension reach the service worker?

This is the part that took me a week to fully accept.

Chrome extensions can inject content scripts into web pages. They can run code in the MAIN world or the ISOLATED world of a page. They can observe network requests, intercept navigations, and modify headers.

What they cannot do is inject code into a third-party website's service worker.

Service workers operate in a separate thread with no DOM, no window, and no connection to the page's JavaScript context. The Chrome Extensions API simply does not offer a mechanism to run extension code inside an arbitrary third-party service worker scope. It's a hard security boundary — and for good reasons. Allowing extensions to arbitrarily patch service workers for any website on the internet would be a significant attack surface.

So: the extension lives on the page side. The push notification lives on the service worker side. There is a wall between them.

Three approaches I investigated

I didn't accept "impossible" without looking for workarounds. Here's what I found.

Approach 1: Override ServiceWorkerRegistration.prototype.showNotification in the MAIN world

A page's JavaScript can call navigator.serviceWorker.ready.then(reg => reg.showNotification(...)). If you override ServiceWorkerRegistration.prototype.showNotification in the MAIN world, you'd intercept that pattern.

The problem: Slack's push notifications don't come from page JavaScript. They come from inside the service worker script itself, where it calls self.registration.showNotification(). The service worker runs in its own scope. The MAIN world prototype override doesn't reach there.

This approach catches one narrow pattern and misses the actual push notification path entirely.

Approach 2: chrome.debugger API with CDP

This is the most discussed workaround in the Chromium Extensions community. The chrome.debugger API gives an extension access to the Chrome DevTools Protocol. With CDP's Fetch.fulfillRequest command, you can intercept a network response — including a service worker JavaScript file — and modify it before the browser processes it. Inject your code into the SW script, and it runs inside the service worker scope.

This technically works. It is completely unusable for a consumer extension.

When you attach the debugger to any tab, Chrome displays a persistent banner at the top of the browser: "Chrome is being controlled by automated test software." This banner appears on every tab. It cannot be dismissed. It cannot be hidden by the extension. The only way to suppress it is to launch Chrome with --silent-debugger-extension-api, which is not something a real user would do.

For a Chrome Web Store extension that people install on their own machine, this approach would immediately look like malware. Ruled out.

Approach 3: declarativeNetRequest

Manifest V3's declarativeNetRequest API lets extensions block or redirect network requests. Could you redirect the Slack service worker script to a modified version?

No. declarativeNetRequest can block or redirect a request, but it cannot modify the response body. And even if it could redirect the service worker script URL, the replacement would need to be served from the same origin as the site — extensions can't serve content from slack.com.

What Firefox can do that Chrome can't

Here's where it gets interesting.

Firefox has an API called webRequest.filterResponseData(). It lets an extension intercept a network response and modify its body before the browser processes it. Applied to a service worker JavaScript file, you could inject code that runs inside the SW scope. That code could override self.registration.showNotification and intercept push notifications.

This capability exists in Firefox. It was advocated for by Giorgio Maone, the developer of NoScript, who needed exactly this kind of deep injection for a privacy tool.

Chrome removed blocking webRequest in MV3 and never added a filterResponseData equivalent. This is one of the more significant functional divergences between the two extension models post-MV3. Extension developers have raised it on the Chromium mailing lists. For now, it's a genuine gap.

What this means for Serious Notification

The extension works well for the constructor path — notifications fired from page JavaScript when a tab is active. For many apps and many use cases, that's most of their notification volume.

For pure push-via-service-worker notifications from backgrounded tabs — like Slack when you've minimised the window — the extension will miss them. I've added a Known Limitations section to the original article to reflect this honestly.

What would need to change for this to be solvable on Chrome? Some form of extension access to service worker scope — whether through a filtered response body API like Firefox's, or through a purpose-built notification interception hook in the Chrome Extensions API. Neither exists today.

If you want to see this change, the Chromium issue tracker is the place to make that case. I'm watching it.

In the meantime, if you want to try what's possible now:

🔗 https://chromewebstore.google.com/detail/hnaggblalhlbihfaegbknioadncpcged?utm_source=devto&utm_medium=content&utm_campaign=article2-sw

How I built a Chrome extension that speaks your notifications aloud — and the two Manifest V3 problems nobody warned me about

M.Bilal Khan — Tue, 07 Jul 2026 19:40:25 +0000

I counted how many times I glanced at a notification during a coding session last week.

Thirty-four times. Only four needed my attention.

So I built Serious Notification — a Chrome extension that speaks browser notifications aloud, but only when they match keywords you set. Type "failed" and only hear build errors. Type "urgent" and only hear what actually matters. Everything else stays silent.

It took a weekend to build the core. The two Manifest V3 architectural problems I hit along the way took longer to figure out. Neither of them is well documented. Here's both.

Problem 1: You can't intercept the Notification API in a regular content script

The plan seemed simple: listen for notifications, check them against keywords, speak the matching ones. A content script listening for notification events should work, right?

No.

Chrome's Notification constructor lives on window. When a website calls new Notification("You have a message"), it's using window.Notification in the page's own JavaScript context.

A standard Manifest V3 content script runs in what Chrome calls an ISOLATED world — a sandboxed environment that shares the DOM with the page but has its own separate JavaScript context. Your content script can read the DOM, but it cannot touch window.Notification on the actual page. By the time your script runs, the page's Notification constructor is completely separate from anything you can reach.

You can listen for a notification after it fires. You cannot intercept it before.

The fix: MAIN world content scripts

Manifest V3 added support for content scripts that run in the MAIN world. Set "world": "MAIN" in your manifest and your script runs directly in the page's JavaScript context — before any page code executes.

{
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["interceptor.js"],
      "world": "MAIN",
      "run_at": "document_start"
    }
  ]
}

Now you can override window.Notification before the page has a chance to use it:

const OriginalNotification = window.Notification;

window.Notification = function(title, options = {}) {
  window.dispatchEvent(
    new CustomEvent('__sn_notification__', {
      detail: { title, body: options.body || '' }
    })
  );
  return new OriginalNotification(title, options);
};

The catch: MAIN world scripts have no Chrome extension APIs

Here is the problem with MAIN world scripts. They run in the page context, which means:

No chrome.storage — you cannot read the user's saved keywords
No speechSynthesis — you cannot speak the notification aloud
No extension APIs at all

You are in the page's world. Chrome's extension APIs are not available there.

So you need two scripts.

The bridge

Script 1 (interceptor.js) runs in the MAIN world. It overrides window.Notification and fires a custom DOM event when a notification arrives.

Script 2 (content.js) runs in the ISOLATED world. It has full access to chrome.storage and speechSynthesis. It listens for the custom event:

window.addEventListener('__sn_notification__', async (e) => {
  const { title, body } = e.detail;
  const data = await chrome.storage.local.get(['enabled', 'keywords', 'speed']);

  if (!data.enabled) return;

  const keywords = data.keywords || [];
  const text = `${title} ${body}`.toLowerCase();
  const match = keywords.some(kw => text.includes(kw.toLowerCase()));

  if (match || keywords.length === 0) {
    const utterance = new SpeechSynthesisUtterance(`${title}. ${body}`);
    utterance.rate = data.speed || 1.0;
    speechSynthesis.speak(utterance);
  }
});

Two scripts. One custom DOM event as the bridge. The MAIN world intercepts, the ISOLATED world decides.

Problem 2: Chrome showed a "read and change all your data on all websites" warning at install

The extension needs to inject on every page — that's legitimate, since you don't know which tab will fire a notification. So <all_urls> host access is genuinely required.

But I was declaring it as a required permission in manifest.json:

"content_scripts": [
  {
    "matches": ["<all_urls>"],
    ...
  }
]

This caused Chrome to show the scariest possible install warning before users had any reason to trust the extension. I was watching my analytics and seeing a 33% uninstall rate. Some of that was almost certainly people bouncing at the permission screen, before they ever heard the extension speak a single word.

The fix: optional host permissions

Manifest V3 supports optional_host_permissions. Move <all_urls> there instead of requiring it at install:

{
  "permissions": ["storage", "scripting"],
  "optional_host_permissions": ["<all_urls>"]
}

Then register content scripts dynamically at runtime using chrome.scripting.registerContentScripts(), only after the user explicitly grants the permission:

// background.js
chrome.permissions.onAdded.addListener(async (permissions) => {
  if (permissions.origins?.includes('<all_urls>')) {
    await chrome.scripting.registerContentScripts([
      {
        id: 'interceptor',
        matches: ['<all_urls>'],
        js: ['interceptor.js'],
        world: 'MAIN',
        runAt: 'document_start',
      },
      {
        id: 'content',
        matches: ['<all_urls>'],
        js: ['content.js'],
        runAt: 'document_start',
      }
    ]);
  }
});

In the popup, show a "Turn on to hear alerts" button that triggers the permission request:

chrome.permissions.request({ origins: ['<all_urls>'] });

The result: the Chrome Web Store install dialog now shows Storage only. No broad-access warning. The scary prompt only appears when the user explicitly clicks "Turn on" inside the popup — after they have already installed the extension and understand what it does.

One edge case: updating from a version that required the permission

When you update an extension and a previously required permission becomes optional, Chrome removes it from the user's granted set. Existing users lose host access silently on update — the extension just stops working with no explanation.

The fix: fire a native notification immediately after update using the notifications permission:

chrome.runtime.onInstalled.addListener(({ reason }) => {
  if (reason === 'update') {
    chrome.notifications.create('update-notice', {
      type: 'basic',
      iconUrl: 'icon.png',
      title: 'Serious Notification — One quick step needed',
      message: 'We improved how permissions work. Open the extension and click "Turn on" to re-enable.',
      requireInteraction: true,
    });
  }
});

Silent failure is the worst outcome for retention. If something breaks on update, tell the user immediately and tell them exactly what to do.

What I built

Serious Notification speaks Chrome notifications aloud when they match keywords you set. Free, no account, works offline. Just shipped v0.2.0 with the optional permissions model above.

If you're building Chrome extensions and hit either of these problems — happy to answer questions in the comments. The MAIN world injection in particular has some edge cases around static property copying (permission, requestPermission) that took me a while to get right.

🔗Serious Notification - Live Chrome WebStore

Known Limitations

This approach only intercepts notifications fired via the Notification constructor in the page's JavaScript context.

Notifications fired from a service worker via registration.showNotification() — which is the path used by background push notifications in apps like Slack — bypass the MAIN world override entirely. The service worker runs in its own scope and never touches the page's window.

Chrome's extension model does not currently offer a hook into arbitrary third-party service workers, so this gap cannot be closed with the current architecture.

The extension works well for in-tab notifications and apps that call the constructor directly from page scripts. For pure push-via-service-worker apps when the tab is backgrounded, it will miss notifications.