7 Things You Need to Know About JavaScript's ShadowRealm

JavaScript developers have long struggled with the language's single-threaded nature, often turning to workarounds like Web Workers or iframes for isolated execution. But a new TC39 proposal, ShadowRealm, promises to change that by providing lightweight, secure execution contexts without the overhead of full browser features. As the proposal advances toward Stage 4, it's time to understand what ShadowRealm offers and why it matters. This article breaks down the key facts you need to know, from clarifying common misconceptions to exploring real-world use cases.

1. Clarifying JavaScript's Single-Threaded Myth

Many developers learn that JavaScript is “single-threaded,” but that framing can be misleading. While the language itself doesn't support multi-threading, a JavaScript application can leverage multiple threads through Web Workers, cross-origin iframes, and similar mechanisms. The more accurate statement is that each JavaScript realm is single-threaded. A realm is the execution environment—like a browser tab or a worker—and each runs on its own thread. This distinction is vital for understanding ShadowRealm, which introduces new ways to create isolated realms without the baggage of full browser contexts.

2. What Exactly Is a Realm?

A realm encompasses the global object, intrinsic objects, and the execution context for JavaScript code. In a browser tab, the realm's global object is the Window interface. Even within an iframe, that iframe has its own Window global, separate from the parent. This isolation ensures that code in one realm cannot accidentally interfere with another—unless explicitly allowed via messaging. However, creating a new realm has traditionally required loading a new document (iframe) or a separate thread (Web Worker), both of which introduce significant overhead. ShadowRealm aims to provide a lighter alternative.

3. Introducing ShadowRealms

ShadowRealm is a new JavaScript primitive that allows you to create an isolated execution context without the heavy setup of an iframe or worker. Unlike those, a ShadowRealm does not require a separate browsing context or thread. It runs synchronously within the same thread as its parent, but its global environment is completely separate. This means code evaluated inside a ShadowRealm cannot access the parent's global variables, DOM, or other resources—only primitives and objects explicitly passed in. The result is a lightweight sandbox ideal for plugin systems, testing frameworks, or any scenario requiring code isolation.

4. How ShadowRealms Work

The API is simple: you create a new ShadowRealm with the ShadowRealm() constructor, then use its evaluate() method to execute code as a string. The evaluated code runs in the realm's own global scope, and any values it returns are wrapped as objects available to the caller. For example, const realm = new ShadowRealm(); realm.evaluate('1 + 2'); // returns 3. Importantly, the realm's global object is not the parent's Window but a new, empty global environment with standard built-ins. This design ensures minimal surface area for potential attacks or accidental interference.

5. Use Cases for ShadowRealms

ShadowRealms shine in scenarios requiring safe code execution without the overhead or latency of iframes or workers. Plugin systems can use them to run third-party code in isolation, preventing malicious or buggy plugins from crashing the main app. Testing libraries can evaluate test suites in separate contexts to avoid state leakage between tests. Even simple “code playground” features benefit from the ability to run user-submitted code without risk. Because ShadowRealms are synchronous, they avoid the complexity of message passing required by workers, making them easier to integrate.

6. Security and Isolation Considerations

While ShadowRealms provide a strong isolation boundary, they are not a complete security panacea. The realm has access to all built-in globals (like Object, Array, Promise), which could be exploited if modified. However, the proposal prevents access to the parent's global, DOM, or any host-specific objects. Developers should still avoid passing sensitive objects into the realm. For high-security needs, combining ShadowRealm with Compartment from the proposed Compartments proposal could offer finer-grained control. As the spec evolves, browser implementations will add security hardening.

7. Current Status and Browser Support

As of 2025, ShadowRealm is at Stage 3 in the TC39 process, meaning the API is largely stable and awaiting implementation feedback. Several browsers have begun experimental support behind flags. A polyfill exists for developers eager to experiment today. The proposal is expected to eventually reach Stage 4 and become part of the ECMAScript standard. Once widely available, ShadowRealm will give JavaScript developers a powerful, lightweight tool for code isolation—finally enabling the kind of sandboxed execution that many applications need without the complexity of current alternatives.

ShadowRealm represents a thoughtful addition to JavaScript's capabilities, addressing long-standing needs for isolated execution without sacrificing simplicity. Whether you're building a plugin system, a testing harness, or a code sandbox, this new primitive can streamline your architecture. Keep an eye on browser support and start exploring the polyfill—your future self will thank you for banishing untrusted code to the ShadowRealm long before it arrives natively.