1 | # Multer [![Build Status](https://travis-ci.org/expressjs/multer.svg?branch=master)](https://travis-ci.org/expressjs/multer) [![NPM version](https://badge.fury.io/js/multer.svg)](https://badge.fury.io/js/multer) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)
|
2 |
|
3 | Multer is a node.js middleware for handling `multipart/form-data`, which is primarily used for uploading files. It is written
|
4 | on top of [busboy](https://github.com/mscdex/busboy) for maximum efficiency.
|
5 |
|
6 | **NOTE**: Multer will not process any form which is not multipart (`multipart/form-data`).
|
7 |
|
8 | ## Installation
|
9 |
|
10 | ```sh
|
11 | npm install --save multer
|
12 | ```
|
13 |
|
14 | ## Usage
|
15 |
|
16 | 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.
|
17 |
|
18 | Basic usage example:
|
19 |
|
20 | ```javascript
|
21 | var multer = require('multer')
|
22 | var express = require('express')
|
23 |
|
24 | var app = express()
|
25 | var upload = multer()
|
26 |
|
27 | app.post('/profile', upload.single('avatar'), function (req, res, next) {
|
28 | // req.file is the `avatar` file
|
29 | // req.body will hold the text fields, if there were any
|
30 | })
|
31 |
|
32 | app.post('/photos/upload', upload.array('photos', 12), function (req, res, next) {
|
33 | // req.files is array of `photos` files
|
34 | // req.body will contain the text fields, if there were any
|
35 | })
|
36 |
|
37 | var cpUpload = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
|
38 | app.post('/cool-profile', cpUpload, function (req, res, next) {
|
39 | // req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
|
40 | //
|
41 | // e.g.
|
42 | // req.files['avatar'][0] -> File
|
43 | // req.files['gallery'] -> Array
|
44 | //
|
45 | // req.body will contain the text fields, if there were any
|
46 | })
|
47 | ```
|
48 |
|
49 | In case you need to handle a text-only multipart form, you can use the `.none()` method, example:
|
50 |
|
51 | ```javascript
|
52 | var multer = require('multer')
|
53 | var express = require('express')
|
54 |
|
55 | var app = express()
|
56 | var upload = multer()
|
57 |
|
58 | app.post('/profile', upload.none(), function (req, res, next) {
|
59 | // req.body contains the text fields
|
60 | })
|
61 | ```
|
62 |
|
63 | ## API
|
64 |
|
65 | ### File information
|
66 |
|
67 | Each file contains the following information:
|
68 |
|
69 | Key | Description
|
70 | --- | ---
|
71 | `fieldName` | Field name specified in the form
|
72 | `originalName` | Name of the file on the user's computer
|
73 | `size` | Size of the file in bytes
|
74 | `stream` | Stream of file
|
75 |
|
76 | ### `multer(opts)`
|
77 |
|
78 | Multer accepts an options object, the following are the options that can be
|
79 | passed to Multer.
|
80 |
|
81 | Key | Description
|
82 | -------- | -----------
|
83 | `limits` | Limits of the uploaded data [(full description)](#limits)
|
84 |
|
85 | #### `.single(fieldname)`
|
86 |
|
87 | Accept a single file with the name `fieldname`. The single file will be stored
|
88 | in `req.file`.
|
89 |
|
90 | #### `.array(fieldname[, maxCount])`
|
91 |
|
92 | Accept an array of files, all with the name `fieldname`. Optionally error out if
|
93 | more than `maxCount` files are uploaded. The array of files will be stored in
|
94 | `req.files`.
|
95 |
|
96 | #### `.fields(fields)`
|
97 |
|
98 | Accept a mix of files, specified by `fields`. An object with arrays of files
|
99 | will be stored in `req.files`.
|
100 |
|
101 | `fields` should be an array of objects with `name` and optionally a `maxCount`.
|
102 | Example:
|
103 |
|
104 | ```javascript
|
105 | [
|
106 | { name: 'avatar', maxCount: 1 },
|
107 | { name: 'gallery', maxCount: 8 }
|
108 | ]
|
109 | ```
|
110 |
|
111 | #### `.none()`
|
112 |
|
113 | Accept only text fields. If any file upload is made, error with code
|
114 | "LIMIT\_UNEXPECTED\_FILE" will be issued. This is the same as doing `upload.fields([])`.
|
115 |
|
116 | #### `.any()`
|
117 |
|
118 | Accepts all files that comes over the wire. An array of files will be stored in
|
119 | `req.files`.
|
120 |
|
121 | **WARNING:** Make sure that you always handle the files that a user uploads.
|
122 | Never add multer as a global middleware since a malicious user could upload
|
123 | files to a route that you didn't anticipate. Only use this function on routes
|
124 | where you are handling the uploaded files.
|
125 |
|
126 | ### `limits`
|
127 |
|
128 | 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](https://github.com/mscdex/busboy#busboy-methods).
|
129 |
|
130 | The following integer values are available:
|
131 |
|
132 | Key | Description | Default
|
133 | --- | --- | ---
|
134 | `fieldNameSize` | Max field name size | 100 bytes
|
135 | `fieldSize` | Max field value size | 1MB
|
136 | `fields` | Max number of non-file fields | Infinity
|
137 | `fileSize` | For multipart forms, the max file size (in bytes) | Infinity
|
138 | `files` | For multipart forms, the max number of file fields | Infinity
|
139 | `parts` | For multipart forms, the max number of parts (fields + files) | Infinity
|
140 | `headerPairs` | For multipart forms, the max number of header key=>value pairs to parse | 2000
|
141 |
|
142 | Specifying the limits can help protect your site against denial of service (DoS) attacks.
|
143 |
|
144 | ## Error handling
|
145 |
|
146 | When encountering an error, multer will delegate the error to express. You can
|
147 | display a nice error page using [the standard express way](http://expressjs.com/guide/error-handling.html).
|
148 |
|
149 | If you want to catch errors specifically from multer, you can call the
|
150 | middleware function by yourself.
|
151 |
|
152 | ```javascript
|
153 | var upload = multer().single('avatar')
|
154 |
|
155 | app.post('/profile', function (req, res) {
|
156 | upload(req, res, function (err) {
|
157 | if (err) {
|
158 | // An error occurred when uploading
|
159 | return
|
160 | }
|
161 |
|
162 | // Everything went fine
|
163 | })
|
164 | })
|
165 | ```
|