DocsAUTO

Control Auto routing

Auto routes a request only after verifying compatibility. Modes change how eligible traffic travels; they do not turn unsupported browser features into proxy features.

Configure Auto once

bootstrap.js — configure routing before loading the app

import { installAuto } from 'https://cors.dev/auto.mjs';

async function start() {
  installAuto({
    key: 'YOUR_CONNECTION_KEY',
    hosts: ['api.example.com'],
    nativeHosts: ['login.example.com'],
    mode: 'native-first',
    xhr: true,
  });

  await import('./app.js');
}

start().catch((error) => {
  console.error('Could not start the application:', error);
});

Hosted Auto options
ESM option	Classic attribute	Behavior
key	data-key	Optional publishable Connection key, sent only to the proxy.
hosts	data-hosts	Exact hostname allowlist. Required for credentials and most custom headers; other hosts stay native.
nativeHosts	data-native-hosts	Exact hostnames that always stay native.
mode	data-mode	native-first by default; modes are described below.
xhr	data-xhr	true by default. Set false to leave XMLHttpRequest untouched.
cacheSeconds	data-cache	Managed GET cache request, whole seconds from 1 to 300. Eligible GETs stay proxy-pinned; hits count.

Pass arrays for ESM hostname options and comma-separated hostnames in HTML attributes. Supply hostnames here, not URLs or wildcards. A repeated installAuto() returns the existing installation; it does not apply new options.

How eligible requests travel

Auto routing modes
Mode	GET and HEAD	Writes
native-first	Native first, then one proxy attempt if the native call rejects before a response. Recently repaired shapes can start at the proxy.	Configured managed route or native; no failure replay.
proxy-first	Proxy first, with at most one native rescue on eligible transport or selected gateway failures.	Same preselected transport; no failure replay.
proxy-only	Proxy route required after compatibility checks; no native rescue.	No native rescue if a required route is unavailable; no failure replay.
native-only	Native only.	Native only.

Readable native HTTP errors, including 401, 403, 429 and 500, are responses, not fallback triggers. App aborts and failures after a Fetch Response is returned do not trigger another attempt. Policy and owner-opt-out rejections do not trigger an automatic native bypass.

Even in proxy-only mode, compatibility guards leave same-origin calls, non-HTTPS targets, cookie-including requests, no-cors, special redirect modes and unsupported inputs native. Non-default Fetch cache settings, integrity and keepalive also stay native. Proxy-only is not a guarantee that all browser traffic uses the proxy.

Leave one-use requests native

A failed native read may already have executed upstream before Auto tries the proxy. For one-use links and GETs with side effects, use the captured native Fetch instead of fallback routing. It still obeys browser CORS.

Classic Auto — keep a one-use URL on the native path

async function openOnce(oneUseUrl) {
  const response = await CorsAuto.nativeFetch(oneUseUrl);

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  return response.text();
}

openOnce('https://api.example.com/one-use-link').then(
  (text) => console.log(text),
  (error) => console.error('Native request failed:', error),
);

With ESM, keep the handle returned by installAuto() and call auto.nativeFetch(url). Use nativeHosts for an entire exact hostname, or mode: "native-only" for the installation.

Install before Axios, jQuery or XHR clients

Load Auto before browser AJAX libraries and application modules capture fetch or XMLHttpRequest. Browser Axios adapters using those transports and ordinary jQuery AJAX calls can then use Auto. JSONP, script-tag transports, WebSocket and EventSource are not intercepted.

Auto decides XHR routing at send(), after headers and request settings are known. Synchronous XHR, document responses, cookie-including calls and unsupported bodies stay native. Proxied XHR responses are buffered upstream; do not depend on incremental upstream progress or identical URL, header and event details.

Clear hints or uninstall

Auto caches bounded, short-lived routing hints in memory, keyed by request shape rather than a whole API host. It does not run background upstream probes or diagnose every network error as CORS. auto.clearRoutes() clears routing and capability hints; the classic equivalent is CorsAuto.clearRoutes().

auto.uninstall() removes its installed wrappers; with the classic script use CorsAuto.uninstall(). Neither clearRoutes nor uninstall cancels in-flight application requests or changes their pending transport selection. Use the request’s AbortController or XHR abort() to cancel it.

Keep going