Middleware for handling
Multer is a node.js middleware for handling
multipart/form-data. It is written
on top of busboy for maximum efficiency.
npm install --save multer
var express = require'express'var multer = require'multer'var upload = multer dest: 'uploads/'var app = expressapppost'/profile' uploadsingle'avatar'// req.file is the `avatar` fileapppost'/photos/upload' uploadarray'photos' 12// req.files is array of `photos` filesvar cpUpload = uploadfields name: 'avatar' maxCount: 1 name: 'gallery' maxCount: 8apppost'/cool-profile' cpUpload// req.files is an object (String -> Array) where fieldname is the key, and the value is array of files//// e.g.// req.files['avatar'] -> File// req.files['gallery'] -> Array
You can access post data fields as
body on the
IMPORTANT: Multer will only process forms which are of the type
Each file contains the following information:
|Field name specified in the form|
|Name of the file on the user's computer|
|Encoding type of the file|
|Mime type of the file|
|Size of the file in bytes|
|The folder to which the file has been saved|
|The name of the file within the |
|The full path to the uploaded file|
Multer accepts an options object, the most basic of which is the
property, which tells Multer where to upload the files. In case you omit the
options object, the file will be renamed and uploaded to the temporary directory
of the system.
By default, Multer will rename the files so as to avoid naming conflicts. The renaming function can be customized according to your needs.
The following are the options that can be passed to Multer.
|Where to store the files|
|Function to control which files are accepted|
|Limits of the uploaded data|
In an average web app, only
dest might be required, and configured as shown in
the following example.
appusemulter dest: 'uploads/'
If you want more control over your uploads, you'll want to use the
option instead of
dest. Multer ships with storage engines
MemoryStorage; More engines are available from third parties.
Accept a single file with the name
fieldname. The single file will be stored
Accept an array of files, all with the name
fieldname. Optionally error out if
maxCount files are uploaded. The array of files will be stored in
Accept a mix of files, specified by
fields. An object with arrays of files
will be stored in
fields should be an array of objects with
name and optionally a
name: 'avatar' maxCount: 1name: 'gallery' maxCount: 8
The disk storage engine gives you full control on storing files to disk.
var storage = multerdiskStoragecbnull '/tmp/my-uploads'cbnull filefieldname + '-' + Datenowappusemulter storage: storage
There are two options available,
filename. They are both
functions that determine where the file should be stored.
destination is used to determine within which folder the uploaded files should
be stored. This can also be given as a
filename is used to determine what the file should be named inside the folder.
Each function gets passed both the request (
req) and some information about
the file (
file) to aid with the decision.
req.body might not have been fully populated yet. It depends on the
order that the client transmits fields and files to the server.
The memory storage engine stores the files in memory as
Buffer objects. It
doesn't have any options.
var storage = multermemoryStorageappusemulter storage: storage
When using memory storage, the file info will contain a field called
buffer that contains the entire file.
WARNING: Uploading very large files, or relatively small files in large numbers very quickly, can cause your application to run out of memory when memory storage is used.
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:
|Max field name size||100 bytes|
|Max field value size||1MB|
|Max number of non-file fields||Infinity|
|For multipart forms, the max file size (in bytes)||Infinity|
|For multipart forms, the max number of file fields||Infinity|
|For multipart forms, the max number of parts (fields + files)||Infinity|
|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.
Set this to a function to control which files should be uploaded and which should be skipped. The function should look like this:
// The function should call `cb` with a boolean// to indicate if the file should be accepted// To reject this file pass `false`, like so:cbnull false// To accept the file pass `true`, like so:cbnull true// You can always pass an error if something goes wrong:cb'I don\'t have a clue!'
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.
var upload = multersingle'avatar'apppost'/profile'uploadreq resif err// An error occurred when uploadingreturn// Everything went fine
See the documentation here if you want to build your own storage engine.