0
# Isomorphic Unfetch
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: isomorphic-unfetch
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install isomorphic-unfetch`
10

11
## Core Imports
12

13
```typescript
14
import fetch from "isomorphic-unfetch";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const fetch = require("isomorphic-unfetch");
21
```
22

23
Browser-specific import:
24

25
```typescript
26
import fetch from "isomorphic-unfetch/browser";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import fetch from "isomorphic-unfetch";
33

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

39
// POST request
40
await fetch("/api/users", {
41
  method: "POST",
42
  headers: {
43
    "Content-Type": "application/json"
44
  },
45
  body: JSON.stringify({ name: "John" })
46
});
47
```
48

49
## Architecture
50

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

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

58
## Capabilities
59

60
### Universal Fetch Function
61

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

64
```typescript { .api }
65
declare function fetch(url: string | URL, opts?: RequestInit): Promise<Response>;
66
```
67

68
### Browser-Specific Export
69

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

72
```typescript { .api }
73
declare function fetch(url: string | URL, opts?: RequestInit): Promise<Response>;
74
```
75

76
## Types
77

78
```typescript { .api }
79
declare namespace unfetch {
80
  /** Union type for Headers that works across environments */
81
  export type IsomorphicHeaders = Headers | NodeHeaders;
82
  
83
  /** Union type for Body that works across environments */
84
  export type IsomorphicBody = Body | NodeBody;
85
  
86
  /** Union type for Response that works across environments */
87
  export type IsomorphicResponse = Response | NodeResponse;
88
  
89
  /** Union type for Request that works across environments */
90
  export type IsomorphicRequest = Request | NodeRequest;
91
  
92
  /** Union type for RequestInit that works across environments */
93
  export type IsomorphicRequestInit = RequestInit | NodeRequestInit;
94
}
95

96
declare const unfetch: typeof fetch;
97
```
98

99
## Environment-Specific Behavior
100

101
### Browser Environment
102
- Uses dynamic import to load the `unfetch` package
103
- The `/browser` export directly imports unfetch and installs it as `self.fetch` if not present
104
- No URL preprocessing
105

106
### Node.js Environment
107
- Uses dynamic import to load the `node-fetch` package
108
- Converts protocol-relative URLs (`//example.com`) to HTTPS (`https://example.com`)  
109
- Supports both string URLs and URL objects
110

111
### Global Installation
112
- Main export installs itself as `global.fetch` if not already present
113
- Browser export installs itself as `self.fetch` if not already present
114

115
## Dependencies
116

117
- **unfetch**: ^5.0.0 (for browser environments)
118
- **node-fetch**: ^3.2.0 (for Node.js environments)
119

120
Dependencies are loaded dynamically based on the runtime environment.