Security News
Combatting Alert Fatigue by Prioritizing Malicious Intent
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Multer is a node.js middleware for handling multipart/form-data, which is primarily used for uploading files. It is written on top of busboy for maximum efficiency.
File Uploads
This feature allows you to upload files to your server. The code sample demonstrates how to handle a single file upload with Multer.
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.single('file'), function (req, res) {
// req.file is the `file` file
res.send('File uploaded!');
});
Multiple Files Upload
Multer also supports uploading multiple files at once. The code sample shows how to handle multiple file uploads, limiting to 12 files in this case.
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.array('files', 12), function (req, res) {
// req.files is array of `files` files
res.send('Multiple files uploaded!');
});
Disk Storage
Multer allows you to customize the storage of files. This code sample demonstrates how to use disk storage to control the storage location and file naming.
const multer = require('multer');
const storage = multer.diskStorage({
destination: function (req, file, cb) {
cb(null, 'uploads/')
},
filename: function (req, file, cb) {
cb(null, file.fieldname + '-' + Date.now())
}
});
const upload = multer({ storage: storage });
Memory Storage
For temporary storage or when you want to process the file without saving it to disk, you can use memory storage. The code sample shows how to store a file in memory.
const multer = require('multer');
const upload = multer({ storage: multer.memoryStorage() });
app.post('/upload', upload.single('file'), function (req, res) {
// req.file is the `file` file stored in memory
res.send('File uploaded and stored in memory!');
});
File Filtering
Multer provides a way to filter out files based on conditions you set. This code sample demonstrates file filtering to only allow JPEG images.
const multer = require('multer');
const upload = multer({
fileFilter: function (req, file, cb) {
if (file.mimetype !== 'image/jpeg') {
return cb(new Error('Only JPEG files are allowed!'), false);
}
cb(null, true);
}
});
Formidable is an alternative to Multer for parsing form data, especially file uploads. It is less middleware-oriented and more flexible in terms of handling various form parsing tasks.
Busboy is a low-level Node.js module for parsing incoming HTML form data. Multer is built on top of Busboy, but provides a more convenient middleware API for integrating with Express.js applications.
Multiparty is another module for handling multipart/form-data requests, which is the type of requests that file uploads usually come in. It is similar to Multer but has a different API and is used in a slightly different way.
Multer is a node.js middleware for handling multipart/form-data
, which is primarily used for uploading files. It is written
on top of busboy for maximum efficiency.
NOTE: Multer will not process any form which is not multipart (multipart/form-data
).
npm install --save multer
Multer adds a body
object and a file
or files
object to the request
object. The body
object contains the values of the text fields of the form, the file
or files
object contains the files uploaded via the form.
Basic usage example:
const multer = require('multer')
const express = require('express')
const app = express()
const upload = multer()
app.post('/profile', upload.single('avatar'), (req, res, next) => {
// req.file is the `avatar` file
// req.body will hold the text fields, if there were any
})
app.post('/photos/upload', upload.array('photos', 12), (req, res, next) => {
// req.files is array of `photos` files
// req.body will contain the text fields, if there were any
})
const cpUpload = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
app.post('/cool-profile', cpUpload, (req, res, next) => {
// req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
//
// e.g.
// req.files['avatar'][0] -> File
// req.files['gallery'] -> Array
//
// req.body will contain the text fields, if there were any
})
In case you need to handle a text-only multipart form, you can use the .none()
method, example:
const multer = require('multer')
const express = require('express')
const app = express()
const upload = multer()
app.post('/profile', upload.none(), (req, res, next) => {
// req.body contains the text fields
})
Each file contains the following information:
Key | Description |
---|---|
fieldName | Field name specified in the form |
originalName | Name of the file on the user's computer (undefined if no filename was supplied by the client) |
size | Size of the file in bytes |
stream | Stream of file |
detectedMimeType | The detected mime-type, or null if we failed to detect |
detectedFileExtension | The typical file extension for files of the detected type, or empty string if we failed to detect (with leading . to match path.extname ) |
clientReportedMimeType | The mime type reported by the client using the Content-Type header, or null1 if the header was absent |
clientReportedFileExtension | The extension of the file uploaded (as reported by path.extname ) |
1 Currently returns text/plain
if header is absent, this is a bug and it will be fixed in a patch release. Do not rely on this behavior.
multer(opts)
Multer accepts an options object, the following are the options that can be passed to Multer.
Key | Description |
---|---|
limits | Limits of the uploaded data (full description) |
.single(fieldname)
Accept a single file with the name fieldname
. The single file will be stored
in req.file
.
.array(fieldname[, maxCount])
Accept an array of files, all with the name fieldname
. Optionally error out if
more than maxCount
files are uploaded. The array of files will be stored in
req.files
.
.fields(fields)
Accept a mix of files, specified by fields
. An object with arrays of files
will be stored in req.files
.
fields
should be an array of objects with name
and optionally a maxCount
.
Example:
[
{ name: 'avatar', maxCount: 1 },
{ name: 'gallery', maxCount: 8 }
]
.none()
Accept only text fields. If any file upload is made, error with code
"LIMIT_UNEXPECTED_FILE" will be issued. This is the same as doing upload.fields([])
.
.any()
Accepts all files that comes over the wire. An array of files will be stored in
req.files
.
WARNING: Make sure that you always handle the files that a user uploads. Never add multer as a global middleware since a malicious user could upload files to a route that you didn't anticipate. Only use this function on routes where you are handling the uploaded files.
limits
An object specifying the size limits of the following optional properties. Multer passes this object into busboy directly, and the details of the properties can be found on busboy's page.
The following integer values are available:
Key | Description | Default |
---|---|---|
fieldNameSize | Max field name size | 100 bytes |
fieldSize | Max field value size | 1MB |
fields | Max number of non-file fields | Infinity |
fileSize | For multipart forms, the max file size (in bytes) | Infinity |
files | For multipart forms, the max number of file fields | Infinity |
parts | For multipart forms, the max number of parts (fields + files) | Infinity |
headerPairs | For multipart forms, the max number of header key=>value pairs to parse | 2000 |
Specifying the limits can help protect your site against denial of service (DoS) attacks.
When encountering an error, multer will delegate the error to express. You can display a nice error page using the standard express way.
If you want to catch errors specifically from multer, you can call the middleware function by yourself.
const upload = multer().single('avatar')
app.post('/profile', (req, res) => {
upload(req, res, (err) => {
if (err) {
// An error occurred when uploading
return
}
// Everything went fine
})
})
FAQs
Middleware for handling `multipart/form-data`.
The npm package multer receives a total of 4,139,357 weekly downloads. As such, multer popularity was classified as popular.
We found that multer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.