0
# Isomorphic Fetch
1
2
Isomorphic Fetch provides a WHATWG Fetch API polyfill that works consistently across Node.js and browser environments. It adds the `fetch` function and related objects to the global scope, enabling cross-platform HTTP requests using the same API regardless of runtime environment.
3
4
## Package Information
5
6
- **Package Name**: isomorphic-fetch
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install isomorphic-fetch`
10
11
## Core Imports
12
13
```javascript
14
require('isomorphic-fetch');
15
// After import, fetch is available globally
16
```
17
18
ES6 modules:
19
20
```javascript
21
import 'isomorphic-fetch';
22
// After import, fetch is available globally
23
```
24
25
Bower:
26
27
```javascript
28
// Bower installs to bower_components/isomorphic-fetch/fetch-bower.js
29
// This simply re-exports the fetch polyfill
30
<script src="bower_components/isomorphic-fetch/fetch-bower.js"></script>
31
```
32
33
## Basic Usage
34
35
```javascript
36
require('isomorphic-fetch');
37
38
fetch('//offline-news-api.herokuapp.com/stories')
39
.then(function(response) {
40
if (response.status >= 400) {
41
throw new Error("Bad response from server");
42
}
43
return response.json();
44
})
45
.then(function(stories) {
46
console.log(stories);
47
});
48
```
49
50
## Architecture
51
52
Isomorphic Fetch works as a polyfill that provides environment-specific implementations:
53
54
- **Node.js Environment**: Uses `node-fetch` internally, adds global objects, and normalizes protocol-relative URLs (`//` → `https://`)
55
- **Browser Environment**: Uses `whatwg-fetch` polyfill which adds fetch to the global scope
56
- **Bower Environment**: Simple re-export mechanism
57
58
The package automatically detects the runtime environment and provides the appropriate implementation without requiring different import patterns.
59
60
## Capabilities
61
62
### Global Fetch Function
63
64
The main fetch function for making HTTP requests. Automatically added to global scope when the package is imported.
65
66
```javascript { .api }
67
/**
68
* Make an HTTP request using the Fetch API
69
* @param {string|Request} url - URL to fetch or Request object
70
* @param {RequestInit} [options] - Optional request configuration
71
* @returns {Promise<Response>} Promise that resolves to the Response object
72
*/
73
function fetch(url: string | Request, options?: RequestInit): Promise<Response>;
74
```
75
76
**Platform-specific behavior:**
77
- **Node.js**: Protocol-relative URLs (`//example.com`) are automatically converted to `https://example.com`
78
- **Browser**: Uses native fetch or whatwg-fetch polyfill behavior
79
80
**Usage Examples:**
81
82
```javascript
83
// Basic GET request
84
fetch('https://api.example.com/data')
85
.then(response => response.json())
86
.then(data => console.log(data));
87
88
// POST request with JSON data
89
fetch('https://api.example.com/users', {
90
method: 'POST',
91
headers: {
92
'Content-Type': 'application/json',
93
},
94
body: JSON.stringify({
95
name: 'John Doe',
96
email: 'john@example.com'
97
})
98
})
99
.then(response => response.json())
100
.then(result => console.log(result));
101
102
// Protocol-relative URL (Node.js automatically converts to https://)
103
fetch('//api.example.com/data')
104
.then(response => response.text())
105
.then(text => console.log(text));
106
107
// Request with AbortSignal for cancellation
108
const controller = new AbortController();
109
const timeoutId = setTimeout(() => controller.abort(), 5000);
110
111
fetch('https://api.example.com/slow-endpoint', {
112
signal: controller.signal
113
})
114
.then(response => response.json())
115
.then(data => {
116
clearTimeout(timeoutId);
117
console.log(data);
118
})
119
.catch(error => {
120
if (error.name === 'AbortError') {
121
console.log('Request was cancelled');
122
} else {
123
console.error('Fetch error:', error);
124
}
125
});
126
```
127
128
### Global Response Object
129
130
Response object constructor provided by the underlying fetch implementation. Available globally after importing isomorphic-fetch.
131
132
```javascript { .api }
133
/**
134
* Response object representing the response to a request
135
* Available globally after importing isomorphic-fetch
136
*/
137
class Response {
138
constructor(body, init);
139
140
// Properties
141
readonly status: number;
142
readonly statusText: string;
143
readonly ok: boolean;
144
readonly headers: Headers;
145
readonly url: string;
146
readonly bodyUsed: boolean;
147
148
// Methods
149
json(): Promise<any>;
150
text(): Promise<string>;
151
blob(): Promise<Blob>;
152
arrayBuffer(): Promise<ArrayBuffer>;
153
clone(): Response;
154
}
155
```
156
157
### Global Headers Object
158
159
Headers object constructor for managing HTTP headers. Available globally after importing isomorphic-fetch.
160
161
```javascript { .api }
162
/**
163
* Headers object for managing HTTP headers
164
* Available globally after importing isomorphic-fetch
165
*/
166
class Headers {
167
constructor(init);
168
169
append(name: string, value: string): void;
170
delete(name: string): void;
171
get(name: string): string | null;
172
has(name: string): boolean;
173
set(name: string, value: string): void;
174
forEach(callback: (value: string, name: string, headers: Headers) => void): void;
175
}
176
```
177
178
### Global Request Object
179
180
Request object constructor for representing HTTP requests. Available globally after importing isomorphic-fetch.
181
182
```javascript { .api }
183
/**
184
* Request object representing an HTTP request
185
* Available globally after importing isomorphic-fetch
186
*/
187
class Request {
188
constructor(input: string | Request, init?: RequestInit);
189
190
// Properties
191
readonly method: string;
192
readonly url: string;
193
readonly headers: Headers;
194
readonly body: ReadableStream | null;
195
readonly bodyUsed: boolean;
196
readonly cache: RequestCache;
197
readonly credentials: RequestCredentials;
198
readonly destination: RequestDestination;
199
readonly integrity: string;
200
readonly keepalive: boolean;
201
readonly mode: RequestMode;
202
readonly redirect: RequestRedirect;
203
readonly referrer: string;
204
readonly referrerPolicy: ReferrerPolicy;
205
206
// Methods
207
clone(): Request;
208
json(): Promise<any>;
209
text(): Promise<string>;
210
blob(): Promise<Blob>;
211
arrayBuffer(): Promise<ArrayBuffer>;
212
}
213
```
214
215
## Types
216
217
```javascript { .api }
218
/**
219
* Request initialization options
220
*/
221
interface RequestInit {
222
method?: string;
223
headers?: HeadersInit;
224
body?: BodyInit | null;
225
mode?: RequestMode;
226
credentials?: RequestCredentials;
227
cache?: RequestCache;
228
redirect?: RequestRedirect;
229
referrer?: string;
230
referrerPolicy?: ReferrerPolicy;
231
integrity?: string;
232
keepalive?: boolean;
233
signal?: AbortSignal | null;
234
}
235
236
/**
237
* Headers initialization types
238
*/
239
type HeadersInit = Headers | Record<string, string> | string[][];
240
241
/**
242
* Body content types
243
*/
244
type BodyInit = Blob | BufferSource | FormData | URLSearchParams | ReadableStream<Uint8Array> | string;
245
246
/**
247
* Request modes
248
*/
249
type RequestMode = "cors" | "no-cors" | "same-origin";
250
251
/**
252
* Credential modes
253
*/
254
type RequestCredentials = "omit" | "same-origin" | "include";
255
256
/**
257
* Cache modes
258
*/
259
type RequestCache = "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached";
260
261
/**
262
* Redirect modes
263
*/
264
type RequestRedirect = "follow" | "error" | "manual";
265
266
/**
267
* Referrer policy types
268
*/
269
type ReferrerPolicy = "" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url";
270
271
/**
272
* Request destination types
273
*/
274
type RequestDestination = "" | "audio" | "audioworklet" | "document" | "embed" | "font" | "frame" | "iframe" | "image" | "manifest" | "object" | "paintworklet" | "report" | "script" | "sharedworker" | "style" | "track" | "video" | "worker" | "xslt";
275
276
/**
277
* Buffer source types
278
*/
279
type BufferSource = ArrayBuffer | ArrayBufferView;
280
```
281
282
## Error Handling
283
284
Isomorphic Fetch follows standard Fetch API error handling patterns:
285
286
- **Network errors**: Promise rejects for network failures
287
- **HTTP error status codes**: Promise resolves normally (check `response.ok` or `response.status`)
288
- **Protocol normalization**: Node.js environment automatically converts `//` URLs to `https://`
289
290
```javascript
291
fetch('https://api.example.com/data')
292
.then(response => {
293
if (!response.ok) {
294
throw new Error(`HTTP error! status: ${response.status}`);
295
}
296
return response.json();
297
})
298
.then(data => console.log(data))
299
.catch(error => console.error('Fetch error:', error));
300
```
301
302
## Platform Compatibility
303
304
- **Node.js**: Uses `node-fetch` (^2.6.1) internally with protocol normalization
305
- **Browser**: Uses `whatwg-fetch` (^3.4.1) polyfill for Fetch API support
306
- **Bower**: Supported via separate entry point (`fetch-bower.js`)
307
- **Browserify**: Supported via browser field in package.json (`fetch-npm-browserify.js`)
308
309
**Dependencies:**
310
- `node-fetch@^2.6.1` - Node.js fetch implementation
311
- `whatwg-fetch@^3.4.1` - Browser fetch polyfill