{"id":15995,"library":"cross-domain-utils","title":"Cross Domain Utils","description":"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.","status":"maintenance","version":"2.0.38","language":"javascript","source_language":"en","source_url":"git://github.com/krakenjs/cross-domain-utils","tags":["javascript","template"],"install":[{"cmd":"npm install cross-domain-utils","lang":"bash","label":"npm"},{"cmd":"yarn add cross-domain-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add cross-domain-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary import for versions < 3.0.0. For v3+, use 'import { getDomain } from '@krakenjs/cross-domain-utils';'","wrong":"const getDomain = require('cross-domain-utils').getDomain;","symbol":"getDomain","correct":"import { getDomain } from 'cross-domain-utils';"},{"note":"Functions are named exports. For v3+, use '@krakenjs/cross-domain-utils'.","wrong":"import isSameDomain from 'cross-domain-utils';","symbol":"isSameDomain","correct":"import { isSameDomain } from 'cross-domain-utils';"},{"note":"CommonJS `require` works but ESM named imports are preferred for modern projects. For v3+, use '@krakenjs/cross-domain-utils'.","wrong":"const { getTop } = require('cross-domain-utils');","symbol":"getTop","correct":"import { getTop } from 'cross-domain-utils';"}],"quickstart":{"code":"import { getDomain, isSameDomain, getTop, getParent, isWindowClosed } from 'cross-domain-utils';\n\nfunction setupIframe(url) {\n  return new Promise(resolve => {\n    const iframe = document.createElement('iframe');\n    iframe.src = url;\n    iframe.onload = () => resolve(iframe);\n    document.body.appendChild(iframe);\n  });\n}\n\nasync function runExample() {\n  const currentWindow = window;\n  console.log(`Current window domain: ${getDomain(currentWindow)}`);\n\n  // Simulate a same-domain iframe\n  const sameDomainIframe = await setupIframe(window.location.href);\n  const sameDomainWin = sameDomainIframe.contentWindow;\n  console.log(`Same-domain iframe loaded. Domain: ${getDomain(sameDomainWin)}`);\n  console.log(`Is same domain as current: ${isSameDomain(sameDomainWin)}`);\n  console.log(`Iframe's parent: ${getParent(sameDomainWin) === currentWindow ? 'current window' : 'other'}`);\n\n  // Simulate a cross-domain iframe (requires a different origin, e.g., a local server on another port)\n  // For demonstration, we'll just illustrate the conceptual call, as actual cross-domain setup is complex.\n  // Replace with a real cross-origin URL for actual testing.\n  const crossDomainUrl = 'http://localhost:8081/other-page.html'; // Example, needs a running server\n  const crossDomainIframe = await setupIframe(crossDomainUrl);\n  const crossDomainWin = crossDomainIframe.contentWindow;\n\n  // Accessing cross-domain properties directly would throw SecurityError.\n  // cross-domain-utils handles this gracefully.\n  console.log(`\nAttempting cross-domain checks...`);\n  console.log(`Is cross-domain window closed: ${isWindowClosed(crossDomainWin)}`); // Safe check\n  console.log(`Is cross-domain window on same domain: ${isSameDomain(crossDomainWin)}`); // Safe check\n\n  try {\n    getDomain(crossDomainWin);\n  } catch (e) {\n    console.warn(`getDomain on cross-domain window threw: ${e.message}`); // Expected behavior\n  }\n\n  const topWindow = getTop(currentWindow);\n  console.log(`Top-level window is current window: ${topWindow === currentWindow}`);\n\n  // Clean up iframes\n  document.body.removeChild(sameDomainIframe);\n  document.body.removeChild(crossDomainIframe);\n}\n\nrunExample();","lang":"javascript","description":"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."},"warnings":[{"fix":"Update your `package.json` dependency and all import statements from `import { ... } from 'cross-domain-utils'` to `import { ... } from '@krakenjs/cross-domain-utils'`.","message":"Starting 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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Several 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Uncaught DOMException: Blocked a frame with origin \"https://example.com\" from accessing a cross-origin frame."},{"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).","cause":"Calling `getDomain(win)` or similar domain-sensitive functions when `win` refers to a window or iframe from a different origin.","error":"Error: Window is not on the same domain as current window"}],"ecosystem":"npm"}