SkillAgentSearch skills...

Xdomain

A pure JavaScript CORS alternative

GenerateConvertImprove

Install / Use

/learn @jpillora/Xdomain
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

XDomain

<a href="https://twitter.com/intent/tweet?hashtags=xdomain&original_referer=http%3A%2F%2Fgithub.com%2F&text=XDomain+-+A+pure+JavaScript+CORS+alternative&tw_p=tweetbutton&url=https%3A%2F%2Fgithub.com%2Fjpillora%2Fxdomain" target="_blank"> <img src="http://jpillora.com/github-twitter-button/img/tweet.png"></img> </a>

Summary

A pure JavaScript CORS alternative. No server configuration required - just add a proxy.html on the domain you wish to communicate with. This library utilizes XHook to hook all XHR, so XDomain will work seamlessly with any library.

Features

  • Simple
  • Library Agnostic
    • With jQuery $.ajax (and subsequently $.get, $.post)
    • With Angular $http service
  • Cross domain XHR just magically works
  • Easy XHR access to file servers:
  • Includes XHook and its features
  • proxy.html files (slaves) may:
    • White-list domains
    • White-list paths using regular expressions (e.g. only allow API calls: /^\/api/)
  • Highly performant
  • Seamless integration with FormData
  • Supports RequiresJS and Browserify

Download

  • Development xdomain.js 27KB

  • Production xdomain.min.js 12KB (5.16KB Gzip)

  • CDN (Latest version is 0.8.2, though you can change to any release tag)

    <script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js"></script>

Live Demos

Browser Support

All except IE6/7 as they don't have postMessage

Quick Usage

Note: It's important to include XDomain before any other library. When XDomain loads, XHook replaces the current window.XMLHttpRequest. So if another library saves a reference to the original window.XMLHttpRequest and uses that, XHook won't be able to intercept those requests.

  1. On your slave domain (http://xyz.example.com), create a small proxy.html file:

    <!DOCTYPE HTML>
<script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js" master="http://abc.example.com"></script>

  2. Then, on your master domain (http://abc.example.com), point to your new proxy.html:

    <script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js" slave="http://xyz.example.com/proxy.html"></script>

  3. And that's it! Now, on your master domain, any XHR to http://xyz.example.com will automagically work:

    //do some vanilla XHR
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://xyz.example.com/secret/file.txt");
xhr.onreadystatechange = function(e) {
  if (xhr.readyState === 4) console.log("got result: ", xhr.responseText);
};
xhr.send();

//or if we are using jQuery...
$.get("http://xyz.example.com/secret/file.txt").done(function(data) {
  console.log("got result: ", data);
});

Tip: If you enjoy being standards compliant, you can also use data-master and data-slave attributes.

Using multiple masters and slaves

The following two snippets are equivalent:

<script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js" master="http://abc.example.com/api/*"></script>

<script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js"></script>
<script>
xdomain.masters({
  'http://abc.example.com': '/api/*'
});
</script>

So, we can then add more masters or (slaves) by simply including them in the object, see API below.

API

xdomain.slaves(slaves)

Will initialize as a master

Each of the slaves must be defined as: origin: proxy file

The slaves object is used as a list slaves to force one proxy file per origin.

The Quick Usage step 2 above is equivalent to:

<script src="//unpkg.com/xdomain@0.8.2/dist/xdomain.min.js"></script>
<script>
  xdomain.slaves({
    "http://xyz.example.com": "/proxy.html"
  });
</script>

xdomain.masters(masters)

Will initialize as a slave

Each of the masters must be defined as: origin: path

origin and path are converted to a regular expression by escaping all non-alphanumeric chars, then converting * into .* and finally wrapping it with ^ and $. path can also be a RegExp literal.

Requests that do not match both the origin and the path regular expressions will be blocked.

So you could use the following proxy.html to allow all subdomains of example.com:

<script src="/dist/xdomain.min.js" data-master="http://*.example.com/api/*.json"></script>

Which is equivalent to:

<script src="/dist/xdomain.min.js"></script>
<script>
  xdomain.masters({
    "http://*.example.com": "/api/*.json"
  });
</script>

Where "/api/*.json" becomes the RegExp /^\/api\/.*\.json$/

Therefore, you could allow ALL domains with the following proxy.html:

<!-- BEWARE: VERY INSECURE -->
<script src="/dist/xdomain.min.js" master="*"></script>

xdomain.debug = false

When true, XDomain will log actions to console

xdomain.timeout = 15e3ms (15 seconds)

Number of milliseconds until XDomains gives up waiting for an iframe to respond

xdomain.on(event, handler)

event may be log, warn or timeout. When listening for log and warn events, handler with contain the message as the first parameter. The timeout event fires when an iframe exeeds the xdomain.timeout time limit.

xdomain.cookies

WARNING :warning: Chrome and possibly other browsers appear to be blocking access to the iframe's document.cookie property. This means Slave-Cookies are no longer supported in some browsers.

When withCredentials is set to true for a given request, the cookies of the master and slave are sent to the server using these names. If one is set to null, it will not be sent.

//defaults
xdomain.cookies = {
  master: "Master-Cookie"
  slave: "Slave-Cookie"
};

Note, if you use "Cookie" as your cookie name, it will be removed by browsers with Disable 3rd Party Cookies switched on - this includes all Safari users and many others who purposefully enable it.

Conceptual Overview

  1. XDomain will create an iframe on the master to the slave's proxy.
  2. Master will communicate to slave iframe using postMessage.
  3. Slave will create XHRs on behalf of master then return the results.

XHR interception is done seamlessly via XHook.

Internet Explorer

Use the HTML5 document type <!DOCTYPE HTML> to prevent your page from going into quirks mode. If you don't do this, XDomain will warn you about the missing JSON and/or postMessage globals and will exit.

If you need a CORS Polyfill and you're here because of IE, give this XHook CORS polyfill a try, however, be mindful of the restrictions listed below.

FAQ / Troubleshooting

Q: But I love CORS

A: You shouldn't. You should use XDomain because:

  • IE uses a different API (XDomainRequest) for CORS, XDomain normalizes this silliness. XDomainRequest also has many restrictions:

    • Requests must be GET or POST
    • Requests must use the same protocol as the page http -> http
    • Requests only emit progress,timeout and error
    • Requests may only use the Content-Type header

  • The CORS spec is not as simple as it seems, XDomain allows you to use plain XHR instead.

  • On a RESTful JSON API server, CORS will generate superfluous traffic by sending a preflight OPTIONS request preceding various types of requests.

  • Not everyone is able to modify HTTP headers on the server, but most can upload a proxy.html file.

  • Google also uses iframes as postMessage proxies instead of CORS in its Google API JS SDK:

    <iframe name="oauth2relay564752183" id="oauth2relay564752183"
src="https://accounts.google.com/o/oauth2/postmessageRelay?..."> </iframe>

Q: XDomain is interfering with another library!

A: XDomain attempts to perfectly implement XMLHttpRequest2 so there should be no differences. If there is a difference, create an issue. Note however, one purposeful difference affects some libraries under IE. Many use the presence of 'withCredentials' in new XMLHttpRequest() to determine if the browser supports CORS.

The most notable library that does this is jQuery, so XHook purposefully defines withCredentials to trick jQuery into thinking the browser supports CORS, thereby allowing XDomain to function seamlessly in IE. However, this fix is detrimental to other libraries like: MixPanel, FB SDK, Intercom as they will incorrectly attempt CORS on domains which don't have a proxy.html. So, if you are using any of these libraries which implement their own CORS workarounds, you can do the following to manually disable defining withCredentials and manually reenable CORS on jQuery:

//fix trackers
xhook.addWithCredentials = false;
//fix jquery cors
jQuery.support.cors = true;

Note: In newer browsers xhook.addWithCredentials has no effect as they already support withCredentials.

Q: XDomain works for a few requests and then it sto

Related Skills

node-connect

340.2k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

84.1k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

340.2k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

commit-push-pr

84.1k

Commit, push, and open a PR

jpillora

View profile

View on GitHub
GitHub Stars3.2k
CategoryDevelopment
Updated23h ago
Forks259
jpillora/xdomain

Languages

JavaScript

Security Score

85/100

Audited on Mar 28, 2026

No findings