Registry / http-networking / cross-domain-utils

cross-domain-utils

JSON →
library2.0.38jsnpmunverified

Cross Domain Utils is a JavaScript utility library designed to simplify and secure interactions between browser windows across different domains. It provides a robust set of functions for safely querying window properties like domain, parent, opener, and child frames, while mitigating common browser security restrictions (e.g., `SecurityError` exceptions). The current stable version for the unscoped `cross-domain-utils` package is 2.0.38, published approximately four years ago. For versions 3.0.0 and above, the package has been migrated to the `@krakenjs/cross-domain-utils` scope. This library is particularly useful for complex iframe communication, secure window management, and scenarios requiring precise control over cross-origin window relationships without triggering browser errors or warnings.

npm install cross-domain-utils
INSTALL
IMPORT
SIG · CROSS-DOMAIN-UTILS
C
cross-domain-utils
http-networkingjavascriptv2.0.38
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

getDomain
import { getDomain } from 'cross-domain-utils';
const getDomain = require('cross-domain-utils').getDomain;
Primary import for versions < 3.0.0. For v3+, use 'import { getDomain } from '@krakenjs/cross-domain-utils';'
isSameDomain
import { isSameDomain } from 'cross-domain-utils';
import isSameDomain from 'cross-domain-utils';
Functions are named exports. For v3+, use '@krakenjs/cross-domain-utils'.
getTop
import { getTop } from 'cross-domain-utils';
const { getTop } = require('cross-domain-utils');
CommonJS `require` works but ESM named imports are preferred for modern projects. For v3+, use '@krakenjs/cross-domain-utils'.

This quickstart demonstrates key utilities like `getDomain`, `isSameDomain`, `getTop`, `getParent`, and `isWindowClosed` in both same-domain and simulated cross-domain scenarios, highlighting how the library handles security boundaries.

import { getDomain, isSameDomain, getTop, getParent, isWindowClosed } from 'cross-domain-utils'; function setupIframe(url) { return new Promise(resolve => { const iframe = document.createElement('iframe'); iframe.src = url; iframe.onload = () => resolve(iframe); document.body.appendChild(iframe); }); } async function runExample() { const currentWindow = window; console.log(`Current window domain: ${getDomain(currentWindow)}`); // Simulate a same-domain iframe const sameDomainIframe = await setupIframe(window.location.href); const sameDomainWin = sameDomainIframe.contentWindow; console.log(`Same-domain iframe loaded. Domain: ${getDomain(sameDomainWin)}`); console.log(`Is same domain as current: ${isSameDomain(sameDomainWin)}`); console.log(`Iframe's parent: ${getParent(sameDomainWin) === currentWindow ? 'current window' : 'other'}`); // Simulate a cross-domain iframe (requires a different origin, e.g., a local server on another port) // For demonstration, we'll just illustrate the conceptual call, as actual cross-domain setup is complex. // Replace with a real cross-origin URL for actual testing. const crossDomainUrl = 'http://localhost:8081/other-page.html'; // Example, needs a running server const crossDomainIframe = await setupIframe(crossDomainUrl); const crossDomainWin = crossDomainIframe.contentWindow; // Accessing cross-domain properties directly would throw SecurityError. // cross-domain-utils handles this gracefully. console.log(` Attempting cross-domain checks...`); console.log(`Is cross-domain window closed: ${isWindowClosed(crossDomainWin)}`); // Safe check console.log(`Is cross-domain window on same domain: ${isSameDomain(crossDomainWin)}`); // Safe check try { getDomain(crossDomainWin); } catch (e) { console.warn(`getDomain on cross-domain window threw: ${e.message}`); // Expected behavior } const topWindow = getTop(currentWindow); console.log(`Top-level window is current window: ${topWindow === currentWindow}`); // Clean up iframes document.body.removeChild(sameDomainIframe); document.body.removeChild(crossDomainIframe); } runExample();
Debug
Known issues
breakingStarting from version 3.0.0, the `cross-domain-utils` package was migrated to the `@krakenjs` npm scope. This means the package name changed from `cross-domain-utils` to `@krakenjs/cross-domain-utils`.
fix
Update your `package.json` dependency and all import statements from `import { ... } from 'cross-domain-utils'` to `import { ... } from '@krakenjs/cross-domain-utils'`.
affects: >=3.0.0
gotchaSeveral utility functions, such as `getDomain`, `isBlankDomain`, and `getUserAgent`, expect the target `Window` object to be on the same domain as the current window or will throw an exception. Use `isSameDomain` first for safe checks.
fix
Always use `isSameDomain(win)` before attempting to call domain-sensitive functions like `getDomain(win)` if the origin of `win` is uncertain. For cross-origin windows, some information is inherently inaccessible due to browser security policies.
affects: >=1.0.0
gotchaThe `isWindowClosed` function has known reliability issues in IE/Edge for frame windows where the iframe element has been dynamically removed from the DOM. In such scenarios, the window object may not reliably indicate its closed status.
fix
Be aware of this limitation, especially when targeting older IE/Edge environments. Consider alternative or supplementary checks for iframe removal from the DOM for critical scenarios.
affects: >=1.0.0
gotchaThe `win.mockDomain` and `win.navigator.mockUserAgent` properties are custom overrides designed solely for testing purposes. Relying on these in production code can lead to unexpected behavior or security vulnerabilities.
fix
Only use `mockDomain` or `mockUserAgent` within test environments to simulate different window origins or user agents. Never use these properties in live application code.
affects: >=1.0.0
Errors
Common errors & fixes
Uncaught DOMException: Blocked a frame with origin "https://example.com" from accessing a cross-origin frame.
Attempting to directly access properties or methods (e.g., `contentWindow.location.href`) of an iframe or window object that is on a different origin due to browser same-origin policy.
fix
Instead of direct access, use `cross-domain-utils` methods like `isSameDomain(win)`, `isWindowClosed(win)`, `getTop(win)` which are designed to handle cross-origin security boundaries gracefully.
Error: Window is not on the same domain as current window
Calling `getDomain(win)` or similar domain-sensitive functions when `win` refers to a window or iframe from a different origin.
fix
Before calling `getDomain(win)`, ensure that `isSameDomain(win)` returns `true`. If `isSameDomain(win)` is `false`, you cannot retrieve the domain for security reasons unless the library provides a specific, safe cross-origin method (which `getDomain` does not for direct access).
Upgrade
Version history
2.0.38latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
cross-domain-utils — npm install cross-domain-utils · libregistry