0
# node-fetch
1

2
node-fetch is a light-weight module that brings the Web Standards Fetch API to Node.js. It provides a consistent, promise-based HTTP client that mirrors the browser's fetch() functionality while adding Node.js-specific enhancements like stream support, HTTP agent configuration, and file system integration.
3

4
## Package Information
5

6
- **Package Name**: node-fetch
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install node-fetch`
10

11
## Core Imports
12

13
```javascript
14
import fetch from 'node-fetch';
15
```
16

17
With named imports:
18

19
```javascript
20
import fetch, { Request, Response, Headers, FormData, FetchError, AbortError } from 'node-fetch';
21
```
22

23
For CommonJS environments (Node.js < 14), use dynamic import:
24

25
```javascript
26
const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
27
```
28

29
## Basic Usage
30

31
```javascript
32
import fetch from 'node-fetch';
33

34
// Simple GET request
35
const response = await fetch('https://api.github.com/users/octocat');
36
const data = await response.json();
37

38
// POST request with JSON body
39
const postResponse = await fetch('https://httpbin.org/post', {
40
  method: 'POST',
41
  headers: { 'Content-Type': 'application/json' },
42
  body: JSON.stringify({ key: 'value' })
43
});
44

45
// Check response status
46
if (response.ok) {
47
  console.log('Request successful');
48
} else {
49
  console.error(`HTTP Error: ${response.status} ${response.statusText}`);
50
}
51
```
52

53
## Architecture
54

55
node-fetch implements the Web Standards Fetch API with these key components:
56

57
- **fetch() Function**: Main HTTP client function accepting URLs and options
58
- **Request/Response Classes**: Full-featured objects representing HTTP requests and responses
59
- **Headers Class**: HTTP header manipulation with case-insensitive operations
60
- **Body Interface**: Shared functionality for reading request/response bodies as text, JSON, streams, etc.
61
- **Error Classes**: Specialized error types for network failures and aborted requests
62
- **Node.js Extensions**: Stream support, HTTP agents, compression, redirect limits, and file utilities
63

64
## Capabilities
65

66
### HTTP Client Operations
67

68
Core fetch functionality for making HTTP requests with full Web Standards compatibility plus Node.js-specific enhancements.
69

70
```javascript { .api }
71
function fetch(url: string | URL | Request, options?: RequestInit): Promise<Response>;
72

73
interface RequestInit {
74
  method?: string;
75
  headers?: HeadersInit;
76
  body?: BodyInit | null;
77
  redirect?: 'follow' | 'error' | 'manual';
78
  signal?: AbortSignal | null;
79
  // Node.js extensions
80
  agent?: http.Agent | ((parsedUrl: URL) => http.Agent);
81
  compress?: boolean;
82
  follow?: number;
83
  size?: number;
84
  highWaterMark?: number;
85
}
86
```
87

88
[HTTP Client Operations](./http-client.md)
89

90
### Request and Response Handling
91

92
Classes for creating and manipulating HTTP requests and responses with full Body interface support.
93

94
```javascript { .api }
95
class Request {
96
  constructor(input: string | URL | Request, init?: RequestInit);
97
  readonly method: string;
98
  readonly url: string;
99
  readonly headers: Headers;
100
  readonly body: ReadableStream | null;
101
  clone(): Request;
102
}
103

104
class Response {
105
  constructor(body?: BodyInit | null, init?: ResponseInit);
106
  readonly status: number;
107
  readonly statusText: string;
108
  readonly ok: boolean;
109
  readonly redirected: boolean;
110
  readonly headers: Headers;
111
  readonly body: ReadableStream | null;
112
  clone(): Response;
113
  static redirect(url: string, status?: number): Response;
114
  static error(): Response;
115
  static json(data: any, init?: ResponseInit): Response;
116
}
117
```
118

119
[Request and Response Handling](./request-response.md)
120

121
### Headers Management
122

123
HTTP header manipulation with case-insensitive operations and Web Standards compatibility.
124

125
```javascript { .api }
126
class Headers {
127
  constructor(init?: HeadersInit);
128
  append(name: string, value: string): void;
129
  delete(name: string): void;
130
  get(name: string): string | null;
131
  has(name: string): boolean;
132
  set(name: string, value: string): void;
133
  forEach(callback: (value: string, key: string, headers: Headers) => void): void;
134
  entries(): IterableIterator<[string, string]>;
135
  keys(): IterableIterator<string>;
136
  values(): IterableIterator<string>;
137
  // Node.js extension
138
  raw(): Record<string, string[]>;
139
}
140
```
141

142
[Headers Management](./headers.md)
143

144
### Body Processing
145

146
Unified interface for reading and processing request/response bodies with support for multiple formats.
147

148
```javascript { .api }
149
interface Body {
150
  readonly body: ReadableStream | null;
151
  readonly bodyUsed: boolean;
152
  arrayBuffer(): Promise<ArrayBuffer>;
153
  blob(): Promise<Blob>;
154
  formData(): Promise<FormData>;
155
  json(): Promise<any>;
156
  text(): Promise<string>;
157
}
158
```
159

160
[Body Processing](./body-processing.md)
161

162
### Error Handling
163

164
Specialized error classes for different types of failures during HTTP operations.
165

166
```javascript { .api }
167
class FetchError extends Error {
168
  constructor(message: string, type: string, systemError?: Record<string, unknown>);
169
  readonly name: 'FetchError';
170
  readonly type: string;
171
  readonly code?: string;
172
  readonly errno?: string;
173
}
174

175
class AbortError extends Error {
176
  constructor(message: string, type?: string);
177
  readonly name: 'AbortError';
178
  readonly type: string;
179
}
180
```
181

182
[Error Handling](./error-handling.md)
183

184
### File and Blob Operations
185

186
Integration with file system and blob operations for uploading files and handling binary data.
187

188
```javascript { .api }
189
// Re-exports from fetch-blob
190
class Blob {
191
  constructor(blobParts?: BlobPart[], options?: BlobPropertyBag);
192
  readonly size: number;
193
  readonly type: string;
194
  arrayBuffer(): Promise<ArrayBuffer>;
195
  stream(): ReadableStream;
196
  text(): Promise<string>;
197
}
198

199
class File extends Blob {
200
  constructor(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag);
201
  readonly name: string;
202
  readonly lastModified: number;
203
}
204

205
// Utility functions
206
function fileFrom(path: string, type?: string): Promise<File>;
207
function fileFromSync(path: string, type?: string): File;
208
function blobFrom(path: string, type?: string): Promise<Blob>;
209
function blobFromSync(path: string, type?: string): Blob;
210
```
211

212
[File and Blob Operations](./file-blob.md)
213

214
### Utility Functions
215

216
Utility functions for HTTP status code validation and common operations.
217

218
```javascript { .api }
219
function isRedirect(code: number): boolean;
220
```
221

222
[Utility Functions](./utilities.md)
223

224
## Types
225

226
```javascript { .api }
227
type HeadersInit = Headers | Record<string, string> | Iterable<readonly [string, string]>;
228

229
type BodyInit = Blob | Buffer | URLSearchParams | FormData | ReadableStream | string;
230

231
type RequestInfo = string | Request;
232

233
interface ResponseInit {
234
  status?: number;
235
  statusText?: string;
236
  headers?: HeadersInit;
237
}
238

239
interface BlobPropertyBag {
240
  type?: string;
241
  endings?: 'transparent' | 'native';
242
}
243

244
interface FilePropertyBag extends BlobPropertyBag {
245
  lastModified?: number;
246
}
247
```