Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 Β· Popup, Options and Content Scripts

The Isolated World and the Page's World

Understand why content scripts cannot see page variables, how the isolated world protects both sides, and how to reach page code with the MAIN world, window.postMessage and custom events.

When a content script and a web page both run on the same tab, you might expect them to share variables. They do not. Chrome runs the content script in an isolated world: it sees the same DOM tree, but it has its own window object with its own globals. This is a security feature, and it surprises almost everyone the first time.

Same DOM, different JavaScript

Imagine the page runs this:

HTML
<script>
  window.appConfig = { user: "ada", debug: true };
  document.title = "Dashboard";
</script>

In your content script:

JavaScript
console.log(document.title);      // "Dashboard"  - the DOM is shared
console.log(window.appConfig);    // undefined    - globals are separate

The DOM belongs to the page, so DOM reads and writes are visible to both worlds. JavaScript objects belong to each world's own heap. The reverse holds too: the page cannot see variables or functions your content script defines, so a page cannot tamper with your logic or steal your data.

flowchart TB
    subgraph Tab
        DOM["Shared DOM"]
        subgraph MAIN["MAIN world (page scripts)"]
            G1["window.appConfig<br/>page libraries"]
        end
        subgraph ISO["ISOLATED world (content script)"]
            G2["your variables<br/>chrome.runtime"]
        end
    end
    G1 --- DOM
    G2 --- DOM
    G1 -. "no direct access" .- G2

The DOM is the only shared surface.

Why it matters

  • Safety for you. The page cannot overwrite Array.prototype.map and break your script, or read your extension's data.
  • Safety for the page. Two extensions cannot clobber each other's globals, and jQuery in your content script does not conflict with the jQuery the page uses.
  • Limits. You cannot read a page's framework state (window.__REDUX_STATE__) or call its functions from the isolated world.

Reaching the page's world

Sometimes you do need the page's JavaScript objects. Chrome offers two main routes.

1. Run code in the MAIN world

A static declaration:

JSON
"content_scripts": [{
  "matches": ["https://app.example.com/*"],
  "js": ["page-hook.js"],
  "world": "MAIN",
  "run_at": "document_start"
}]

Or with chrome.scripting.executeScript({ ..., world: "MAIN" }), covered in programmatic injection. A MAIN-world script sees the page's globals, but it loses extension APIs: no chrome.runtime, no chrome.storage, and it is exposed to the page (untrusted).

2. Talk across worlds with events

A MAIN-world script (which can read page variables) and an isolated-world script (which can use extension APIs) can talk through the DOM using events or window.postMessage:

JavaScript
// page-hook.js  (MAIN world)
window.dispatchEvent(new CustomEvent("myext:config", {
  detail: { user: window.appConfig?.user ?? null },
}));
JavaScript
// content.js  (ISOLATED world)
window.addEventListener("myext:config", (e) => {
  chrome.runtime.sendMessage({ type: "config", user: e.detail.user });
});

CustomEvent detail objects are not shared between worlds the way you hope (they are cloned), so pass only plain data: strings, numbers, arrays, simple objects.

Treat anything from the page as untrusted. A page can fire your event with any content, or postMessage anything. Validate the shape and never use eval or innerHTML on it. Check event.source === window and a message type when you use postMessage.

Simulating two worlds

You cannot create two real JavaScript worlds on this page, but you can model the rule with a pair of separate scopes that only share a message channel. This stand-in shows the pattern: a page-world function reads private state and publishes a sanitized event; the isolated side validates it.

JS Two scopes, one event channel

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A page with both sides, visible

The next stand-in shows the shared DOM idea: two scripts, one writes to an element and one reads it, while their variables stay private.

Shared DOM, private variables

Quick decision guide

You want to… Use
Read or edit DOM, add UI Isolated world (default)
Call chrome.storage, chrome.runtime Isolated world
Read a page's global variable or framework state MAIN world script + event to isolated world
Patch fetch or XMLHttpRequest on the page MAIN world at document_start
Keep secrets from the page Isolated world only

Check your understanding

Quick check Β· 3 questions

of 3 answered You scored / 3 Β· perfect!

  1. 1. A page sets window.appConfig. What does a content script in the default world see for window.appConfig?

    The isolated world has its own window globals; only the DOM tree is shared.
  2. 2. What do you lose when you run a script in the MAIN world?

    MAIN-world code runs like a page script and has no extension APIs.
  3. 3. How should you treat data received from the page through a custom event?

    A hostile page can send anything, so always validate type and shape and avoid innerHTML or eval.

Summary

  • Content scripts share the DOM with the page but not JavaScript globals.
  • Isolation protects your script from page tampering and avoids library clashes.
  • Use world: "MAIN" plus events or postMessage to bridge to page variables.
  • MAIN-world scripts have no extension APIs and are exposed to the page.
  • Validate everything that crosses the boundary.

Next: Injecting Scripts Programmatically