JavaScript's much-repeated "single-threaded" label is accurate in the narrow computer-science sense — script execution proceeds linearly, one execution context at a time — but it stops being a useful framing once Web Workers enter the picture, since they let code run on another thread. The more precise statement is that a JavaScript realm is single-threaded. A realm is the environment in which code executes: a browser tab is one, with its main thread inside it; a Web Worker is a realm with a worker thread; a cross-origin iframe runs on that iframe's main thread. Individual functions can't be shipped off to another thread, because the language itself is single-threaded, but an application can span multiple realms — each with its own global environment, global object and intrinsic objects — and those realms can communicate in specific, limited ways.
Global scope as a shared liability
In a browser tab the global object is the Window interface, and a non-same-origin iframe within that tab has its own Window:
<html>
<head></head>
<body>
<iframe id="theIframe"></iframe>
</body>
<script>
( () => {
console.log( window.globalThis );
// Result: Window {}
console.log( theIframe.contentWindow.globalThis );
// Result: Window {}
})();
</script>
</html>
Those are not the same object:
<html>
<head></head>
<body>
<iframe id="theIframe"></iframe>
</body>
<script>
( () => {
console.log( window.globalThis === theIframe.contentWindow.globalThis );
// Result: false
})();
</script>
</html>
The outer page and the inner iframe are separate realms, each single-threaded, each with its own global and intrinsic objects:
<html>
<head></head>
<body>
<iframe id="theIframe"></iframe>
</body>
<script>
(() => {
console.log( window.Array );
/* Result (expanded):
function Array()
from: function from()
fromAsync: function fromAsync()
isArray: function isArray()
length: 1
name: "Array"
of: function of()
prototype: Array []
Symbol(Symbol.species): undefined
<prototype>: function ()
*/
console.log( theIframe.contentWindow.Array );
/* Result (expanded):
function Array()
from: function from()
fromAsync: function fromAsync()
isArray: function isArray()
length: 1
name: "Array"
of: function of()
prototype: Array []
Symbol(Symbol.species): undefined
<prototype>: function ()
*/
console.log( window.Array === theIframe.contentWindow.Array );
// Result: false
})();
</script>
</html>
Globals defined in one realm are therefore unavailable to another — or, seen from the other side, unable to interfere with it:
<html>
<head></head>
<body>
<iframe id="theIframe"></iframe>
</body>
<script>
function globalFunction() {};
console.log( window.globalFunction );
// Result: function globalFunction()
console.log( theIframe.contentWindow.globalFunction );
// Result: undefined
</script>
</html>
That isolation matters because global environments get messy. A stray variable binding is partly to blame, but much of the clutter traces back to early language design decisions, such as function declarations. Add the volume of JavaScript a typical project doesn't control — frameworks, third-party helper libraries, polyfills, analytics, ads — and collisions become a real possibility. Hence the appeal of a sandbox: a place to run part of a test suite in a clean room where the act of testing can't skew results and mock data can't collide with real code, or to quarantine third-party libraries that don't need global access from the realm hosting the application.
Existing realms can't fill that role. Since each realm is single-threaded, we can't repurpose an alternate realm to execute code on its thread and then fold the results back into the primary realm's main thread: that is multi-threaded execution by definition. JavaScript permitting multiple simultaneous threads of execution would mean problems us new for.
A realm without a thread
What's needed is a new kind of realm: one with its own global and intrinsic objects but no thread of its own, where offloaded code still runs on the main thread of the realm that owns the script. That is the ShadowRealm. A ShadowRealm has no execution context; code sent into it lives in a pseudo-realm whose global and built-ins are its own, while execution continues on the creating code's thread — no cross-thread resource sharing required. Effectively the script runs as it would within a single realm, but quarantined from the outer realm's intrinsic objects, APIs, global object and whatever the script has done to that global object.
The proposed API is simple in practice:
// Create a ShadowRealm:
const shadow = new ShadowRealm();
function globalFunction() {};
console.log( globalthis.globalFunction );
// Result: function globalFunction()
// Evaluate `globalThis.globalFunction` inside the ShadowRealm:
console.log( shadow.evaluate( 'globalThis.globalFunction' ) );
// Result: undefined
Note: this code is theoretical — it does not yet exist in the ES-262 standard or in browsers.
A globalFunction defined on the outer realm's global object, as above, is absent from the new ShadowRealm's global object, which stays pristine regardless of what happens outside it. The reverse holds too:
// Create a ShadowRealm:
const shadow = new ShadowRealm();
// Declare a global function inside the ShadowRealm:
shadow.evaluate( 'function globalFunction() {};' );
// It doesn't exist in the outer realm's global object:
console.log( globalthis.globalFunction );
// Result: undefined
// But when we evaluate `globalThis.globalFunction` inside the ShadowRealm:
console.log( shadow.evaluate( 'globalThis.globalFunction' ) );
// Result: function globalFunction()
A function declared inside the ShadowRealm is callable through the variable that references that ShadowRealm object, and stays quarantined from the outer global object and from any other ShadowRealm:
// Create a ShadowRealm:
const firstShadow = new ShadowRealm();
const secondShadow = new ShadowRealm();
// Declare a global function inside the ShadowRealm referenced by `secondShadow`:
secondShadow.evaluate( 'function globalFunction() {};' );
// It doesn't exist in the outer realm's global object:
console.log( globalthis.globalFunction );
// Result: undefined
// It doesn't exist in the global object of the ShadowRealm referencd by `firstShadow`:
console.log( firstShadow.evaluate( 'globalThis.globalFunction' ) );
// Result: undefined
// It only exists within the ShadowRealm referenced by `secondShadow`:
console.log( secondShadow.evaluate( 'globalThis.globalFunction' ) );
// Result: function globalFunction()
Boundaries, not airtight walls
Quarantine has limits. ShadowRealms are not a true security boundary: code inside one can still make inferences about code in other realms. They can be regarded as an integrity boundary, since code in a ShadowRealm cannot directly interfere with another realm unless permitted to. And results produced inside a ShadowRealm are usable outside it just as the same operation's results would be in the host realm:
// Create a ShadowRealm:
const shadow = new ShadowRealm();
// Create a binding that calls a function inside the ShadowRealm:
const shadowFunction = shadow.evaluate( '( value ) => globalThis.someValue = value );
// ...and call our wrapped function using that binding:
shadowFunction( "Hello from the ShadowRealm!" );
// Executing this function in the host realm doesn't _change_ anything here, of course:
console.log( globalThis.someValue );
// Result: undefined
// But we can grab the result from the ShadowRealm:
const shadowValue = shadow.evaluate( 'globalThis.someValue' );
// And use it here in the host realm:
console.log( shadowValue );
// Result: Hello from the ShadowRealm!
The result is effectively an endless supply of disposable clean rooms — pocket dimensions for running arbitrary code without fear of it interfering with any other ShadowRealm or with the outer, "light" realm.
Not just goth eval
Developers who remember JavaScript's early days may reasonably see evaluate as eval with extra steps, and not entirely wrongly: apart from running in a ShadowRealm's context, the examples above amount to indirect calls to eval, and they fall under the same unsafe-eval rule in a Content Security Policy. Those examples are illustrative, not the only option. The proposal also adds an importValue method on the ShadowRealm object's prototype for dynamically importing modules and capturing their exported values and functions:
// spookycode.js
export function greeting() {
return "Hello from the ShadowRealm!";
}
async function shadowGreeter() {
// I INVOKE THE DARK POWER OF THE SHADOWREALM- ahem. Sorry.
const shadow = new ShadowRealm();
/*
* `importValue` returns a promise that resolves with the value of the function
* specified in the second argument:
*/
const shadowGreet = await shadow.importValue( "./spookycode.js", "greeting" );
// Call our wrapped function, annnnd...
shadowGreet();
}
shadowGreeter();
// Result: Hello from the ShadowRealm!
Status: not yet
That covers the whole of the proposed API: two methods, evaluate and importValue, both ways to evaluate code in a ShadowRealm instance while still executing it on the host realm's thread. None of it is usable yet. The specification sits at Stage 2.7 — "approved in principle and undergoing validation" — meaning it is likely to change only in response to feedback from tests and trial browser implementations, if at all. When it reaches Stage 3 and browser implementations appear, it will be ready to try.



