# express-fileupload
Simple express middleware for uploading files.
[](https://www.npmjs.org/package/express-fileupload)
[](https://travis-ci.org/richardgirges/express-fileupload)
[](https://www.npmjs.org/package/express-fileupload)
[](https://coveralls.io/r/richardgirges/express-fileupload)
# Version 1.0.0 Breaking Changes
Breaking change to `md5` handling. [Read about it here.](https://github.com/richardgirges/express-fileupload/releases/tag/v1.0.0-alpha.1)
# Install
```bash
# With NPM
npm install --save express-fileupload
# With Yarn
yarn add express-fileupload
```
# Usage
When you upload a file, the file will be accessible from `req.files`.
Example:
* You're uploading a file called **car.jpg**
* Your input's name field is **foo**: ``
* In your express server request, you can access your uploaded file from `req.files.foo`:
```javascript
app.post('/upload', function(req, res) {
console.log(req.files.foo); // the uploaded file object
});
```
The **req.files.foo** object will contain the following:
* `req.files.foo.name`: "car.jpg"
* `req.files.foo.mv`: A function to move the file elsewhere on your server
* `req.files.foo.mimetype`: The mimetype of your file
* `req.files.foo.data`: A buffer representation of your file
* `req.files.foo.truncated`: A boolean that represents if the file is over the size limit
* `req.files.foo.md5`: A function that returns an MD5 checksum of the uploaded file
### Examples
* [Example Project](https://github.com/richardgirges/express-fileupload/tree/master/example)
* [Basic File Upload](https://github.com/richardgirges/express-fileupload/tree/master/example#basic-file-upload)
* [Multi-File Upload](https://github.com/richardgirges/express-fileupload/tree/master/example#multi-file-upload)
### Using Busboy Options
Pass in Busboy options directly to the express-fileupload middleware. [Check out the Busboy documentation here.](https://github.com/mscdex/busboy#api)
```javascript
app.use(fileUpload({
limits: { fileSize: 50 * 1024 * 1024 },
}));
```
### Using useTempFile Options
Use temp files instead of memory for managing the upload process.
Please note: md5 hashes will not be generated when using tempFiles
```javascript
app.use(fileUpload({
useTempFiles : true,
tempFileDir : '/tmp/'
}));
```
### Available Options
Pass in non-Busboy options directly to the middleware. These are express-fileupload specific options.
Option | Acceptable Values | Details
--- | --- | ---
createParentPath |
false **(default)**
true
| Automatically creates the directory path specified in `.mv(filePathName)`
safeFileNames |
false **(default)**
true
regex
| Strips characters from the upload's filename. You can use custom regex to determine what to strip. If set to `true`, non-alphanumeric characters _except_ dashes and underscores will be stripped. This option is off by default.
| Preserves filename extension when using safeFileNames option. If set to true, will default to an extension length of 3. If set to *Number*, this will be the max allowable extension length. If an extension is smaller than the extension length, it remains untouched. If the extension is longer, it is shifted.
| Returns a HTTP 413 when the file is bigger than the size limit if true. Otherwise, it will add a truncate = true to the resulting file structure.
useTempFiles |
false **(default)**
true
| Will use temporary files at the specified tempDir for managing uploads rather than using buffers in memory. This avoids memory issues when uploading large files.
tempFileDir |
String **(path)**
| Used with the useTempFiles option. Path to the directory where temp files will be stored during the upload process. Add trailing slash.
parseNested |
false **(default)**
true
| By default, req.body and req.files are flattened like this: {'name': 'John', 'hobbies[0]': 'Cinema', 'hobbies[1]': 'Bike'}
When this option is enabled they are parsed in order to be nested like this: {'name': 'John', 'hobbies': ['Cinema', 'Bike']}
# Help Wanted
Looking for additional maintainers. Please contact `richardgirges [ at ] gmail.com` if you're interested. Pull Requests are welcomed!
# Thanks & Credit
[Brian White](https://github.com/mscdex) for his stellar work on the [Busboy Package](https://github.com/mscdex/busboy) and the [connect-busboy Package](https://github.com/mscdex/connect-busboy)