Global Polyfills

Install web standard global APIs in Node.js environments to enable compatibility with web-standard code.

Capabilities

Install Globals

Installs global polyfills for web standards in Node.js environments using either undici or @remix-run/web-fetch.

/**
 * Install web standard global APIs in Node.js environments
 * @param options - Configuration options
 * @param options.nativeFetch - If true, use undici's native fetch; otherwise use @remix-run/web-fetch (default: false)
 */
function installGlobals(options?: { nativeFetch?: boolean }): void;

Installed Globals:

• global.fetch - Fetch API for making HTTP requests
• global.Request - Request constructor for creating request objects
• global.Response - Response constructor for creating response objects
• global.Headers - Headers constructor for managing HTTP headers
• global.FormData - FormData constructor for handling form data
• global.File - File constructor for file handling

Note: ReadableStream and WritableStream are declared in TypeScript types for better IDE support but are not polyfilled by this function.

Usage Examples:

import { installGlobals } from "@remix-run/node";

// Install globals using @remix-run/web-fetch (default)
installGlobals();

// Now you can use web standard APIs
const response = await fetch("https://api.example.com/data");
const data = await response.json();

// Install globals using undici's native fetch
installGlobals({ nativeFetch: true });

// Use undici's faster native implementation
const response = await fetch("https://api.example.com/data");

Implementation Details:

When nativeFetch: false (default), uses @remix-run/web-fetch polyfills:

• Provides consistent behavior across Node.js versions
• Full compatibility with web standards
• Suitable for most applications

When nativeFetch: true, uses undici's native implementations:

• Better performance for high-throughput applications
• Native Node.js implementation
• Requires Node.js 18+ for optimal compatibility

Environment Configuration:

The function extends Node.js global types to include web standard APIs:

declare global {
  namespace NodeJS {
    interface Global {
      File: typeof File;
      Headers: typeof Headers;
      Request: typeof Request;
      Response: typeof Response;
      fetch: typeof fetch;
      FormData: typeof FormData;
      ReadableStream: typeof ReadableStream;
      WritableStream: typeof WritableStream;
    }
  }

  interface RequestInit {
    duplex?: "half";
  }
}

Note: The TypeScript declarations include ReadableStream and WritableStream for IDE support, but only fetch, Request, Response, Headers, FormData, and File are actually installed as globals.