0
# Multer
1

2
Multer is a Node.js middleware for handling `multipart/form-data`, which is primarily used for uploading files. Built on top of busboy for maximum efficiency, it provides comprehensive file upload functionality for Express.js applications with flexible storage options, file filtering, and upload constraints.
3

4
## Package Information
5

6
- **Package Name**: multer
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Node.js Version**: >= 10.16.0
10
- **Installation**: `npm install multer`
11

12
## Core Imports
13

14
```javascript
15
const multer = require('multer');
16
```
17

18
For ES modules:
19

20
```javascript
21
import multer from 'multer';
22
```
23

24
## Basic Usage
25

26
```javascript
27
const express = require('express');
28
const multer = require('multer');
29
const upload = multer({ dest: 'uploads/' });
30

31
const app = express();
32

33
// Single file upload
34
app.post('/profile', upload.single('avatar'), (req, res) => {
35
  // req.file contains the uploaded file
36
  // req.body contains the text fields
37
  console.log(req.file);
38
});
39

40
// Multiple file upload
41
app.post('/photos', upload.array('photos', 12), (req, res) => {
42
  // req.files contains array of uploaded files
43
  console.log(req.files);
44
});
45

46
// Mixed field upload
47
app.post('/profile-complete', upload.fields([
48
  { name: 'avatar', maxCount: 1 },
49
  { name: 'gallery', maxCount: 8 }
50
]), (req, res) => {
51
  // req.files is an object with fieldname as key
52
  console.log(req.files['avatar']);
53
  console.log(req.files['gallery']);
54
});
55
```
56

57
## Architecture
58

59
Multer is organized around several key components:
60

61
- **Main Factory Function**: Creates multer instances with configurable options
62
- **Middleware Methods**: Various upload strategies (single, array, fields, none, any)
63
- **Storage Engines**: Pluggable storage backends (disk, memory, custom)
64
- **File Filtering**: Control which files are accepted for upload
65
- **Error Handling**: Comprehensive error reporting with custom error types
66
- **Limits**: Configurable upload constraints for security
67

68
## Capabilities
69

70
### Core Middleware
71

72
Primary multer factory function and instance methods for creating upload middleware tailored to different use cases.
73

74
```javascript { .api }
75
function multer(options?: MulterOptions): MulterInstance;
76

77
interface MulterInstance {
78
  single(fieldname: string): RequestHandler;
79
  array(fieldname: string, maxCount?: number): RequestHandler;
80
  fields(fields: FieldConfig[]): RequestHandler;
81
  none(): RequestHandler;
82
  any(): RequestHandler;
83
}
84
```
85

86
[Core Middleware](./core-middleware.md)
87

88
### Storage Engines
89

90
File storage backends that determine where and how uploaded files are stored, with built-in disk and memory storage options.
91

92
```javascript { .api }
93
const diskStorage = multer.diskStorage(options: DiskStorageOptions);
94
const memoryStorage = multer.memoryStorage();
95

96
interface DiskStorageOptions {
97
  destination?: string | ((req: Request, file: File, cb: (error: Error | null, destination: string) => void) => void);
98
  filename?: (req: Request, file: File, cb: (error: Error | null, filename: string) => void) => void;
99
}
100
```
101

102
[Storage Engines](./storage-engines.md)
103

104
### Error Handling
105

106
Comprehensive error handling with custom error types for different upload failure scenarios.
107

108
```javascript { .api }
109
class MulterError extends Error {
110
  constructor(code: string, field?: string);
111
  code: string;
112
  field?: string;
113
}
114

115
// Error codes
116
const LIMIT_PART_COUNT: string;
117
const LIMIT_FILE_SIZE: string;
118
const LIMIT_FILE_COUNT: string;
119
const LIMIT_FIELD_KEY: string;
120
const LIMIT_FIELD_VALUE: string;
121
const LIMIT_FIELD_COUNT: string;
122
const LIMIT_UNEXPECTED_FILE: string;
123
const MISSING_FIELD_NAME: string;
124
```
125

126
[Error Handling](./error-handling.md)
127

128
## Types
129

130
### Configuration Options
131

132
```javascript { .api }
133
interface MulterOptions {
134
  dest?: string;
135
  storage?: StorageEngine;
136
  limits?: LimitsOptions;
137
  preservePath?: boolean;
138
  fileFilter?: (req: Request, file: File, cb: FileFilterCallback) => void;
139
}
140

141
interface LimitsOptions {
142
  fieldNameSize?: number;
143
  fieldSize?: number;
144
  fields?: number;
145
  fileSize?: number;
146
  files?: number;
147
  parts?: number;
148
  headerPairs?: number;
149
}
150

151
interface FieldConfig {
152
  name: string;
153
  maxCount?: number;
154
}
155
```
156

157
### File Object
158

159
```javascript { .api }
160
interface File {
161
  fieldname: string;
162
  originalname: string;
163
  encoding: string;
164
  mimetype: string;
165
  size: number;
166
  // DiskStorage specific
167
  destination?: string;
168
  filename?: string;
169
  path?: string;
170
  // MemoryStorage specific
171
  buffer?: Buffer;
172
}
173
```
174

175
### Core Types
176

177
```javascript { .api }
178
interface MulterInstance {
179
  single(fieldname: string): RequestHandler;
180
  array(fieldname: string, maxCount?: number): RequestHandler;
181
  fields(fields: FieldConfig[]): RequestHandler;
182
  none(): RequestHandler;
183
  any(): RequestHandler;
184
}
185

186
interface StorageEngine {
187
  _handleFile(req: Request, file: File, cb: (error: Error | null, info?: any) => void): void;
188
  _removeFile(req: Request, file: File, cb: (error: Error | null) => void): void;
189
}
190

191
// Express framework types
192
interface Request {
193
  body: any;
194
  file?: File;
195
  files?: File[] | { [fieldname: string]: File[] };
196
  [key: string]: any;
197
}
198

199
interface Response {
200
  send(body?: any): Response;
201
  json(body?: any): Response;
202
  status(code: number): Response;
203
  [key: string]: any;
204
}
205

206
type NextFunction = (err?: any) => void;
207
```
208

209
### Callback Types
210

211
```javascript { .api }
212
type FileFilterCallback = (error: Error | null, acceptFile: boolean) => void;
213
type RequestHandler = (req: Request, res: Response, next: NextFunction) => void;
214
```