0
# Core Middleware
1

2
Primary multer functionality for creating upload middleware instances with different upload strategies and configuration options.
3

4
## Capabilities
5

6
### Multer Factory Function
7

8
Creates a multer instance configured with the specified options.
9

10
```javascript { .api }
11
/**
12
 * Creates a multer instance with the given configuration options
13
 * @param options - Configuration object for upload behavior
14
 * @returns MulterInstance with middleware methods
15
 */
16
function multer(options?: MulterOptions): MulterInstance;
17

18
interface MulterOptions {
19
  /** Destination directory (shorthand for diskStorage) */
20
  dest?: string;
21
  /** Storage engine instance */
22
  storage?: StorageEngine;
23
  /** Upload limits configuration */
24
  limits?: LimitsOptions;
25
  /** Keep full file paths instead of just basename */
26
  preservePath?: boolean;
27
  /** Function to control which files are accepted */
28
  fileFilter?: (req: Request, file: File, cb: FileFilterCallback) => void;
29
}
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
const multer = require('multer');
36

37
// Simple configuration with destination directory
38
const upload = multer({ dest: 'uploads/' });
39

40
// Advanced configuration with custom storage and limits
41
const upload = multer({
42
  storage: multer.diskStorage({
43
    destination: './public/uploads',
44
    filename: (req, file, cb) => {
45
      cb(null, Date.now() + '-' + file.originalname);
46
    }
47
  }),
48
  limits: {
49
    fileSize: 1024 * 1024 * 5, // 5MB limit
50
    files: 3 // Maximum 3 files
51
  },
52
  fileFilter: (req, file, cb) => {
53
    if (file.mimetype.startsWith('image/')) {
54
      cb(null, true);
55
    } else {
56
      cb(new Error('Only image files allowed'), false);
57
    }
58
  }
59
});
60
```
61

62
### Single File Upload
63

64
Accept a single file with the specified field name.
65

66
```javascript { .api }
67
/**
68
 * Creates middleware to handle single file upload
69
 * @param fieldname - Name of the form field containing the file
70
 * @returns Express middleware function
71
 */
72
single(fieldname: string): RequestHandler;
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
// HTML form
79
// <form action="/profile" method="post" enctype="multipart/form-data">
80
//   <input type="file" name="avatar" />
81
// </form>
82

83
app.post('/profile', upload.single('avatar'), (req, res) => {
84
  if (req.file) {
85
    console.log('File uploaded:', req.file.originalname);
86
    console.log('File size:', req.file.size);
87
    console.log('File path:', req.file.path);
88
  }
89
  res.send('Upload successful');
90
});
91
```
92

93
### Array File Upload
94

95
Accept an array of files with the same field name, optionally limiting the count.
96

97
```javascript { .api }
98
/**
99
 * Creates middleware to handle multiple files with same field name
100
 * @param fieldname - Name of the form field containing the files
101
 * @param maxCount - Maximum number of files to accept (optional)
102
 * @returns Express middleware function
103
 */
104
array(fieldname: string, maxCount?: number): RequestHandler;
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
// HTML form
111
// <form action="/photos" method="post" enctype="multipart/form-data">
112
//   <input type="file" name="photos" multiple />
113
// </form>
114

115
app.post('/photos', upload.array('photos', 12), (req, res) => {
116
  if (req.files && req.files.length > 0) {
117
    console.log(`Uploaded ${req.files.length} files`);
118
    req.files.forEach((file, index) => {
119
      console.log(`File ${index + 1}:`, file.originalname);
120
    });
121
  }
122
  res.send('Upload successful');
123
});
124
```
125

126
### Mixed Field Upload
127

128
Accept multiple files with different field names and individual count limits.
129

130
```javascript { .api }
131
/**
132
 * Creates middleware to handle files from multiple form fields
133
 * @param fields - Array of field configurations with names and limits
134
 * @returns Express middleware function
135
 */
136
fields(fields: FieldConfig[]): RequestHandler;
137

138
interface FieldConfig {
139
  name: string;
140
  maxCount?: number;
141
}
142
```
143

144
**Usage Examples:**
145

146
```javascript
147
// HTML form
148
// <form action="/profile" method="post" enctype="multipart/form-data">
149
//   <input type="file" name="avatar" />
150
//   <input type="file" name="gallery" multiple />
151
// </form>
152

153
const uploadFields = upload.fields([
154
  { name: 'avatar', maxCount: 1 },
155
  { name: 'gallery', maxCount: 8 }
156
]);
157

158
app.post('/profile', uploadFields, (req, res) => {
159
  if (req.files) {
160
    // req.files is an object with fieldname as key
161
    if (req.files['avatar']) {
162
      console.log('Avatar:', req.files['avatar'][0].originalname);
163
    }
164
    if (req.files['gallery']) {
165
      console.log(`Gallery: ${req.files['gallery'].length} images`);
166
    }
167
  }
168
  res.send('Upload successful');
169
});
170
```
171

172
### Text-Only Upload
173

174
Accept only text fields, rejecting any file uploads.
175

176
```javascript { .api }
177
/**
178
 * Creates middleware that accepts only text fields, no files
179
 * @returns Express middleware function that rejects file uploads
180
 */
181
none(): RequestHandler;
182
```
183

184
**Usage Examples:**
185

186
```javascript
187
// For forms that should only contain text data
188
app.post('/contact', upload.none(), (req, res) => {
189
  // Only req.body will be populated with text fields
190
  console.log('Name:', req.body.name);
191
  console.log('Email:', req.body.email);
192
  console.log('Message:', req.body.message);
193
  res.send('Message received');
194
});
195
```
196

197
### Any File Upload
198

199
Accept all files sent over the wire, regardless of field name.
200

201
```javascript { .api }
202
/**
203
 * Creates middleware that accepts any files from any field
204
 * @returns Express middleware function that accepts all files
205
 */
206
any(): RequestHandler;
207
```
208

209
**Usage Examples:**
210

211
```javascript
212
// WARNING: Use with caution - accepts files from any field
213
app.post('/upload-anything', upload.any(), (req, res) => {
214
  if (req.files && req.files.length > 0) {
215
    console.log(`Received ${req.files.length} files from various fields`);
216
    req.files.forEach(file => {
217
      console.log(`Field: ${file.fieldname}, File: ${file.originalname}`);
218
    });
219
  }
220
  res.send('Upload successful');
221
});
222
```
223

224
## Configuration Details
225

226
### Limits Configuration
227

228
```javascript { .api }
229
interface LimitsOptions {
230
  /** Max field name size in bytes (default: 100) */
231
  fieldNameSize?: number;
232
  /** Max field value size in bytes (default: 1MB) */
233
  fieldSize?: number;
234
  /** Max number of non-file fields (default: Infinity) */
235
  fields?: number;
236
  /** Max file size in bytes (default: Infinity) */
237
  fileSize?: number;
238
  /** Max number of file fields (default: Infinity) */
239
  files?: number;
240
  /** Max number of parts (fields + files) (default: Infinity) */
241
  parts?: number;
242
  /** Max number of header key-value pairs (default: 2000) */
243
  headerPairs?: number;
244
}
245
```
246

247
### File Filter Function
248

249
```javascript { .api }
250
/**
251
 * Function to control which files should be uploaded
252
 * @param req - Express request object
253
 * @param file - File information object
254
 * @param cb - Callback to accept or reject the file
255
 */
256
type FileFilterFunction = (
257
  req: Request,
258
  file: File,
259
  cb: (error: Error | null, acceptFile: boolean) => void
260
) => void;
261
```
262

263
**File Filter Examples:**
264

265
```javascript
266
// Accept only images
267
const imageFilter = (req, file, cb) => {
268
  if (file.mimetype.startsWith('image/')) {
269
    cb(null, true);
270
  } else {
271
    cb(new Error('Only image files are allowed'), false);
272
  }
273
};
274

275
// Accept only specific file types
276
const documentFilter = (req, file, cb) => {
277
  const allowedTypes = ['application/pdf', 'application/msword', 'text/plain'];
278
  if (allowedTypes.includes(file.mimetype)) {
279
    cb(null, true);
280
  } else {
281
    cb(null, false); // Silently reject
282
  }
283
};
284

285
// Size-based filtering (additional to limits)
286
const sizeFilter = (req, file, cb) => {
287
  // This example shows logic, but size filtering is better done via limits
288
  cb(null, true);
289
};
290

291
const upload = multer({
292
  dest: 'uploads/',
293
  fileFilter: imageFilter
294
});
295
```