Isomorphic Unfetch

Isomorphic Unfetch is a universal fetch implementation that automatically switches between unfetch for browser environments and node-fetch for Node.js environments. It provides a single import that works across all JavaScript runtime environments.

Package Information

• Package Name: isomorphic-unfetch
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install isomorphic-unfetch

Core Imports

import fetch from "isomorphic-unfetch";

For CommonJS:

const fetch = require("isomorphic-unfetch");

Browser-specific import:

import fetch from "isomorphic-unfetch/browser";

Basic Usage

import fetch from "isomorphic-unfetch";

// Works in both browser and Node.js
const response = await fetch("https://api.example.com/data");
const data = await response.json();
console.log(data);

// POST request
await fetch("/api/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "John" })
});

Architecture

Isomorphic Unfetch uses environment detection to automatically load the appropriate fetch implementation:

• Browser Environment: Uses dynamic imports to load the unfetch package
• Node.js Environment: Uses dynamic imports to load the node-fetch package
• URL Preprocessing: In Node.js, converts protocol-relative URLs (//example.com) to https://example.com
• Global Installation: The main export automatically installs itself as global.fetch if not already present

Capabilities

Universal Fetch Function

The main export provides a fetch function that automatically detects the runtime environment and uses the appropriate implementation.

declare function fetch(url: string | URL, opts?: RequestInit): Promise<Response>;

Browser-Specific Export

Available via the /browser subpath, this provides a browser-only implementation that uses unfetch or falls back to the native browser fetch.

declare function fetch(url: string | URL, opts?: RequestInit): Promise<Response>;

Types

declare namespace unfetch {
  /** Union type for Headers that works across environments */
  export type IsomorphicHeaders = Headers | NodeHeaders;
  
  /** Union type for Body that works across environments */
  export type IsomorphicBody = Body | NodeBody;
  
  /** Union type for Response that works across environments */
  export type IsomorphicResponse = Response | NodeResponse;
  
  /** Union type for Request that works across environments */
  export type IsomorphicRequest = Request | NodeRequest;
  
  /** Union type for RequestInit that works across environments */
  export type IsomorphicRequestInit = RequestInit | NodeRequestInit;
}

declare const unfetch: typeof fetch;

Environment-Specific Behavior

Browser Environment

• Uses dynamic import to load the unfetch package
• The /browser export directly imports unfetch and installs it as self.fetch if not present
• No URL preprocessing

Node.js Environment

• Uses dynamic import to load the node-fetch package
• Converts protocol-relative URLs (//example.com) to HTTPS (https://example.com)
• Supports both string URLs and URL objects

Global Installation

• Main export installs itself as global.fetch if not already present
• Browser export installs itself as self.fetch if not already present

Dependencies

• unfetch: ^5.0.0 (for browser environments)
• node-fetch: ^3.2.0 (for Node.js environments)

Dependencies are loaded dynamically based on the runtime environment.