gmFetch

Drop-in fetch() replacement for userscripts, powered by GM_xmlhttpRequest. Supports cross-origin requests, forbidden headers, cookie injection, proxies, streaming, and upload progress while preserving familiar Fetch API ergonomics.

Available in three variants:

• Full (~3.3 KB min, ~1.7 KB gzip) — closely aligned with Fetch spec, SRI, streaming, cache modes, GM options
• Lite (~2.0 KB min, ~1.0 KB gzip) — core fetch semantics, AbortSignal, forbidden headers
• Micro (~0.8 KB min, ~0.5 KB gzip) — absolute minimum for simple GET/POST, no abort, no timeout

// Full
import gmFetch from "@kobzi/gmfetch";

// Lite
import gmFetch from "@kobzi/gmfetch/lite";

// Micro
import gmFetch from "@kobzi/gmfetch/micro";

// IIFE (classic userscript)
// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.iife.min.js
// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.lite.iife.min.js
// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.micro.iife.min.js

const r = await gmFetch("https://api.example.com/data");
const data = await r.json();

Full vs Lite vs Micro

Use Micro when: simple GET/POST, grab JSON, size is everything, no abort needed.

Use Lite when: need AbortSignal, forbidden headers (Cookie/UA), proper error handling.

Use Full when: need GM-specific features, SRI, streaming, cache control, progress events.

Installation

Bundler (ES module)

import gmFetch from "@kobzi/gmfetch";       // full
import gmFetch from "@kobzi/gmfetch/lite";   // lite
import gmFetch from "@kobzi/gmfetch/micro";  // micro

CDN (IIFE, no bundler)

// ==UserScript==
// @grant   GM_xmlhttpRequest
// @connect example.com
// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.iife.min.js
// ==/UserScript==

const r = await gmFetch("https://example.com/api");

Or for lite/micro:

// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.lite.iife.min.js
// @require https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.micro.iife.min.js

The IIFE exposes gmFetch as a global. Pin to a specific version for stability.

@grant GM_xmlhttpRequest (or GM.xmlHttpRequest) required. @connect <domain> required for cross-origin.

Compatibility

Runtime: crypto.subtle (for SRI, full only).

API

function gmFetch(input: RequestInfo | URL, init?: GmFetchInit): Promise<Response>

Signature matches window.fetch(). The full version extends init with an optional gm field:

interface GmFetchInit extends RequestInit {
  gm?: GmOptions;  // full only
}

Standard RequestInit fields

GmOptions — the gm field (full only)

Only whitelisted keys are forwarded (protects internal callbacks):

Request body

The body is sent in the format that matches its type, so servers receive what they expect:

Text bodies are forwarded directly rather than wrapped in a Blob with binary: true. This matters because some servers reject or mishandle binary blob uploads when they expect a plain JSON/form payload. The Content-Type computed by the Request constructor is always included in the request headers regardless of body type.

// Sent as a normal JSON text body, not a binary blob
await gmFetch("https://api.example.com/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "thing" }),
});

Empty bodies are omitted entirely (no empty Blob or empty string is dispatched). Applies to all three variants.

Firefox note: body detection is based on the original init.body, not on Request.body. Some userscript engines (notably Firefox) expose Request.body as null even when a body was supplied; relying on it would silently drop POST payloads. Fixed in 1.3.1.

Headers

Pass as plain object or array of tuples to preserve forbidden headers:

await gmFetch("https://example.com", {
  headers: {
    "Cookie": "session=abc",
    "User-Agent": "Custom/1.0",
    "Referer": "https://other.com",
  },
});

⚠️ new Headers({ Cookie: "x" }) strips forbidden headers at construction. Use plain objects.

Response Set-Cookie

const r = await gmFetch("https://example.com/login", { method: "POST" });
const cookies = r.headers.getSetCookie(); // ["session=abc; HttpOnly", ...]

Note: Set-Cookie availability depends on userscript engine and browser. Tampermonkey exposes it; other engines may vary.

Cookies

Sending cookies via headers works in full and lite (forbidden headers preserved). In micro, cookies via headers only work if the browser doesn't strip them (use full/lite for reliable cookie injection). The gm.cookie option (additive patching) is full only.

Timeouts and abort

// AbortSignal (standard) — works in both full and lite
await gmFetch(url, { signal: AbortSignal.timeout(5000) });

// gm.timeout — immune to tab throttling (full only)
await gmFetch(url, { gm: { timeout: 5000 } });

// Manual abort
const ctrl = new AbortController();
gmFetch(url, { signal: ctrl.signal });
ctrl.abort();

All produce DOMException with name "TimeoutError" or "AbortError" (full and lite only — micro has no abort/timeout support).

Errors

The message is kept spec-generic (native fetch never leaks network failure details). For debugging, network errors (onerror and status: 0) attach the raw GM event on error.cause in full and lite, so you can inspect status, statusText, finalUrl, responseHeaders, etc.:

try {
  await gmFetch("https://example.com");
} catch (e) {
  console.error(e.message);        // "Failed to fetch"
  console.error(e.cause?.error);   // GM-provided detail, if any
  console.error(e.cause?.finalUrl);
}

Micro throws a bare TypeError("Failed to fetch") with no cause.

Examples

POST JSON (all variants)

const r = await gmFetch("https://api.example.com/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "thing" }),
});

Forbidden headers (full and lite)

const r = await gmFetch("https://example.com/protected", {
  headers: {
    "Cookie": "session=abc; user_id=42",
    "User-Agent": "Mozilla/5.0 (custom)",
    "Referer": "https://example.com/login",
  },
});

Progress reporting (full)

// Download progress
await gmFetch("https://example.com/big.zip", {
  gm: {
    onprogress: ({ loaded, total, lengthComputable }) => {
      if (lengthComputable) console.log(`Download: ${(loaded / total * 100).toFixed(1)}%`);
    },
  },
});

// Upload progress — not available in native fetch!
await gmFetch("https://example.com/upload", {
  method: "POST",
  body: largeBlob,
  gm: {
    onuploadprogress: ({ loaded, total }) => {
      console.log(`Upload: ${(loaded / total * 100).toFixed(1)}%`);
    },
  },
});

Streaming (full)

const r = await gmFetch("https://example.com/stream");
const reader = r.body!.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process(value);
}

Proxy (full, Firefox, TM 5.5+)

await gmFetch("https://example.com", {
  gm: { proxy: { type: "socks", host: "127.0.0.1", port: 9050, proxyDNS: true } },
});

SRI integrity (full)

const r = await gmFetch("https://cdn.example.com/lib.js", {
  integrity: "sha384-OLBgp1GsljhM2TJ+sbHjaiH9txEUvgdDTAzHv2P24donTt6/529l+9Ua0vFImLlb",
});

Full example (CDN/IIFE)

// ==UserScript==
// @name        Scraper
// @grant       GM_xmlhttpRequest
// @connect     api.example.com
// @require     https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.iife.min.js
// ==/UserScript==

(async () => {
  const r = await gmFetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Cookie": "auth=abc", "User-Agent": "Bot/1.0" },
    body: JSON.stringify({ query: "test" }),
    signal: AbortSignal.timeout(15_000),
    cache: "no-store",
    gm: { onprogress: ({ loaded }) => console.log(loaded) },
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  console.log(await r.json());
})();

Lite example

// ==UserScript==
// @name        Simple Fetch
// @grant       GM_xmlhttpRequest
// @connect     api.example.com
// @require     https://cdn.jsdelivr.net/npm/@kobzi/gmfetch@latest/dist/gmFetch.lite.iife.min.js
// ==/UserScript==

(async () => {
  const r = await gmFetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Cookie": "auth=abc", "Content-Type": "application/json" },
    body: JSON.stringify({ query: "test" }),
    signal: AbortSignal.timeout(10_000),
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  console.log(await r.json());
})();

Limitations

Silently ignored (no GM equivalent): mode, referrer, referrerPolicy, keepalive, priority, window. Note: the Referer header can still be set manually via headers: { "Referer": "..." } — only the automatic policy fields are ignored.

Not supported (GM_xmlhttpRequest limitation):

• duplex: "half" — upload streaming is not possible; body is always fully buffered before sending.
• response.trailer — HTTP trailers are not exposed by GM.
• Request body streaming — bodies are never streamed. Text bodies (string, URLSearchParams) are passed through as-is; binary bodies (Blob, ArrayBuffer, typed arrays, FormData) are buffered to a Blob before dispatch.

Spec-divergent:

• redirect: "manual" — returns 3xx with readable Location header (spec says opaque response with status: 0). GM gives more info than spec allows.
• cache: "force-cache" — falls back to default (no GM equivalent)
• credentials: "same-origin" — behaves like "include" (GM is privileged)
• response.type — always "basic" (GM bypasses CORS entirely)
• response.clone() — works for blob responses; may fail for streaming responses depending on TM/browser implementation details.

Building

npm install
npm run build

Output:

dist/
├── gmFetch.esm.min.js          3364 B  (full, ESM)
├── gmFetch.iife.min.js         3383 B  (full, IIFE)
├── gmFetch.lite.esm.min.js     2036 B  (lite, ESM)
├── gmFetch.lite.iife.min.js    2055 B  (lite, IIFE)
├── gmFetch.micro.esm.min.js     808 B  (micro, ESM)
├── gmFetch.micro.iife.min.js    813 B  (micro, IIFE)
├── gmFetch.d.ts                (types, full)
├── gmFetch.lite.d.ts           (types, lite)
└── gmFetch.micro.d.ts          (types, micro)

Sizes (esbuild + terser, minified):

For comparison (IIFE, minified):

Pipeline: esbuild (bundle + minify, target es2024) → terser (3-pass compress + toplevel mangle).

The build targets ES2024 (modern browsers). If you need to support older environments, fork and change --target in package.json scripts.

Zero runtime dependencies. Dev: esbuild + terser + typescript.

TypeScript

// Full
import gmFetch, {
  type GmFetchInit,
  type GmOptions,
  type GmProxyConfig,
  type GmProgressEvent,
} from "@kobzi/gmfetch";

// Lite
import gmFetch, { type GmFetchLiteInit } from "@kobzi/gmfetch/lite";

// Micro
import gmFetch, { type GmFetchMicroInit } from "@kobzi/gmfetch/micro";

Requires lib: ["ES2024", "DOM"]. For IIFE usage, add a .d.ts with declare function gmFetch(...).

Background

Inspired by @sec-ant/gm-fetch and @trim21/gm-fetch. This library goes further — carefully aligned Fetch semantics, preserved forbidden headers, full GM API surface, SRI integrity, and a lite variant for size-conscious scripts.

Comparison

¹ Silently ignored — no GM_xmlhttpRequest equivalent exists. ² GM returns full 3xx response with headers/body instead of opaque redirect.

Key advantages over alternatives:

• vs @sec-ant: forbidden headers support, AbortSignal cleanup (no memory leak), signal.reason propagation, no vite-plugin-monkey dependency
• vs @trim21: correct binary body handling (trim21 corrupts via .text()), proper header parsing, correct redirected flag, Set-Cookie access, smaller when minified
• vs gmxhr-fetch: AbortSignal, Request normalisation, Response properties, TypeScript, error semantics — gmxhr-fetch is a bare-minimum wrapper with no spec compliance
• vs @uwx/gm-fetch: 4x smaller (3.3 vs 12.4 KB), minified build included, no custom Response class overhead

Security model

gmFetch runs through the userscript manager's privileged networking layer. This means:

• CORS restrictions do not apply
• Forbidden request headers can be sent freely
• Cookies may be injected or observed across origins
• Requests bypass page-level CSP and fetch restrictions

Users are responsible for respecting website policies, privacy, and applicable laws.

Changelog

1.3.1

• Fix (full + lite): POST bodies were silently dropped in Firefox userscript engines because body presence was detected via Request.body (which Firefox exposes as null even when a body is supplied). Detection now uses the original init.body. Endpoints that returned HTTP 400 on bodyless POSTs work again.

License

MIT.