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
```