Content Scripts in Chrome Extensions: The Practical Guide

Content scripts are the part of a Chrome extension that runs inside a web page. They can read and modify the DOM — but they live in an isolated JavaScript world, separate from the page's own scripts.

What content scripts can and can't do

• Can: read the DOM, modify it, inject UI elements, listen to events.
• Can't: access the page's JavaScript variables directly.
• Can't: use most `chrome.*` APIs — only `chrome.runtime` and `chrome.storage`.
• Can: send messages to the service worker for anything else.

The message-passing pattern

When a content script needs something only the service worker can do — calling an external API, opening a new tab, reading `chrome.tabs` — it uses `chrome.runtime.sendMessage`. The service worker listens via `chrome.runtime.onMessage.addListener` and responds asynchronously.

Injecting UI cleanly

Use Shadow DOM for any UI you inject. It isolates your CSS from the host page so your overlay isn't broken by site-specific styles, and your styles don't leak into the page.

A minimal, robust pattern looks like this: create a host element, attach a shadow root in open mode, and render everything inside it. Because the host page can re-render at any time, append the host to document.documentElement rather than document.body, and re-check on a MutationObserver tick that your node is still attached.

Registering the script: manifest vs. programmatic

There are two ways to run a content script. Declarative registration in manifest.json under content_scripts fires automatically on matching URLs. Programmatic injection via chrome.scripting.executeScript runs on demand from the service worker and only needs the activeTab permission, which reviewers treat far more kindly than a broad host permission.

• Declarative: predictable, runs before your popup exists, but needs host permissions up front.
• Programmatic: minimal permissions, runs only after a user gesture, better for Web Store review.
• run_at: 'document_idle' is the safe default; use 'document_start' only when you must beat the page's own scripts.
• all_frames: true is needed for iframe-heavy sites (Gmail, Notion) and is a common cause of 'it works on some pages'.

Talking to the page's own JavaScript

Because of the isolated world, you cannot read window variables the page defined. If you genuinely need them, inject a <script> tag whose src points at a web_accessible_resource in your extension, then relay data back to the content script with window.postMessage and an origin check. Never eval strings — Manifest V3's content security policy blocks it and the Web Store rejects it.

Surviving single-page apps

YouTube, Twitter/X, and most modern apps never reload the document, so a content script that runs once and exits will look broken after the first navigation. Watch for URL changes with a MutationObserver on document.title or by listening for the service worker's chrome.tabs.onUpdated event, and re-run your setup idempotently.

Debugging checklist

1. Open DevTools on the page and switch the console context dropdown to your extension — content script logs do not appear in the default context.
2. Check chrome://extensions for a red 'Errors' badge; manifest match-pattern typos surface there.
3. Confirm your match pattern includes the scheme (https://*.example.com/* — not example.com).
4. If the script never fires on a subframe, set all_frames: true.
5. If styles look wrong, you're leaking into the page — move the UI into a Shadow DOM.

Generate a working content script instead

Every rule above is encoded in ManifestGo's builder. Describe the page behaviour you want and it produces the manifest entry, the isolated-world content script, the Shadow DOM UI, and the service-worker message handlers as one coherent, installable Manifest V3 project.

Manifest fields you'll actually configure

• matches — array of match patterns like 'https://*.example.com/*'; a bare domain without scheme or trailing '/*' silently matches nothing.
• exclude_matches — carve out subdomains or paths (e.g. exclude '*://mail.example.com/*' while matching the rest of the domain).
• css — inject stylesheet files declaratively alongside js, useful for hiding elements before the script runs to avoid a flash of unstyled content.
• world: 'MAIN' — new in Chrome 111+, lets content_scripts run directly in the page's own JS context without a separate injected <script> tag, replacing the old postMessage relay for simple cases.

declarativeContent and page-conditional activation

chrome.declarativeContent.PageStateMatcher lets you show the action icon only on pages matching a CSS selector or URL pattern, without granting host_permissions to read page content — useful when you only need to react to page structure, not read its data.

Common console errors and their fixes

• 'Refused to execute inline script because it violates the following Content Security Policy directive' — your injected <script> uses inline code; move it to a separate file listed in web_accessible_resources.
• 'Cannot access contents of the page. Extension manifest must request permission to access the respective host' — the URL wasn't covered by host_permissions or activeTab wasn't invoked by a user gesture first.
• 'A listener indicated an asynchronous response by returning true, but the message channel closed' — sendResponse was called after the channel already timed out; keep async work under the response window or use chrome.runtime.connect for long-lived channels.

Performance: avoiding jank on every page load

A content script injected with run_at: 'document_start' blocks the page's own parsing until it finishes executing synchronous code. Keep document_start scripts to a few lines (usually just a CSS injection to prevent flicker) and defer everything else to document_idle or a requestIdleCallback inside the script.

MutationObserver patterns that don't leak memory

Always call observer.disconnect() when your target element is removed, and scope observers to the smallest container element possible rather than document.body — observing the whole document on a high-traffic SPA like Gmail can measurably slow down typing and scrolling.

web_accessible_resources in Manifest V3

Unlike MV2's flat array of filenames, MV3 requires an object with resources and matches: { resources: ['injected.js'], matches: ['https://*.example.com/*'] }. Forgetting the matches key is the most common reason 'Denying load of chrome-extension://...' appears in the page console.