references/extensions/content-scripts.md
GitHubContent Scripts & DOM Manipulation
Two Ways to Inject
1. Static (manifest declaration)
{
"content_scripts": [{
"matches": ["<all_urls>"],
"js": ["content/content.js"],
"css": ["content/content.css"],
"run_at": "document_idle"
}]
}
2. Programmatic (from service worker or popup)
// Requires "scripting" permission and host access
chrome.scripting.executeScript({
target: { tabId: tabId },
files: ['content/content.js']
});
// Or inject a function directly
chrome.scripting.executeScript({
target: { tabId: tabId },
func: (param) => {
document.body.style.backgroundColor = param;
},
args: ['yellow']
});
Use activeTab permission for on-click injection (no host_permissions needed):
{
"permissions": ["activeTab", "scripting"]
}
Isolated World
Content scripts run in an isolated world:
- They share the DOM with the page but NOT JavaScript variables
- They can access chrome.runtime messaging APIs
- The page's CSP does NOT restrict content script code
windowrefers to the content script's isolated world
Message Passing from Content Scripts
// content.js → service worker
chrome.runtime.sendMessage({ type: 'DATA', payload: data }, (response) => {
console.log('Got response:', response);
});
// service worker → content script in a specific tab
chrome.tabs.sendMessage(tabId, { type: 'UPDATE', data: newData });
// content.js: listen for messages
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === 'GET_CONTENT') {
const text = document.body.innerText;
sendResponse({ text });
}
return true; // Keep channel open for async sendResponse
});
DOM Manipulation Best Practices
- Avoid blocking the main thread when modifying many DOM elements. Use
requestAnimationFrameto batch visual updates andscheduler.yield()to break up long-running tasks:
// ❌ BAD: Blocks the main thread while processing hundreds of elements
const emails = document.body.innerText.match(/[\w.+-]+@[\w-]+\.[\w.]+/g);
emails.forEach(email => {
// ... find and highlight each email (can freeze the page)
});
// ✅ GOOD: Process in batches using requestAnimationFrame
async function highlightEmails(elements) {
const BATCH_SIZE = 20;
for (let i = 0; i < elements.length; i += BATCH_SIZE) {
const batch = elements.slice(i, i + BATCH_SIZE);
await new Promise(resolve => requestAnimationFrame(() => {
batch.forEach(el => el.style.backgroundColor = 'yellow');
resolve();
}));
// Yield to the main thread between batches
if (typeof scheduler !== 'undefined' && scheduler.yield) {
await scheduler.yield();
}
}
}
- Use
MutationObserverfor dynamic pages (SPAs, infinite scroll) - Namespace your CSS classes to avoid conflicts (e.g.,
myext-highlight) - Use Shadow DOM for complex UI injected into pages
- Clean up on removal:
chrome.runtime.onMessagelisteners persist until the content script context is destroyed - Use
TreeWalkerordocument.createNodeIteratorinstead of regex oninnerHTMLfor finding text in the DOM — this is more reliable and doesn't break event listeners
run_at Timing
| Value | When |
|---|---|
document_start |
Before DOM is constructed (useful for blocking) |
document_idle |
After DOM is ready but before all resources load (default, recommended) |
document_end |
After DOM is complete but before images/subframes |