Skip to content

Commit a1090b8

Browse files
richardgirgesrichardgirges
committed
Clearer and more organized documentation. This closes #12 
1 parent 06da130 commit a1090b8

File tree

1 file changed

+78
-45
lines changed

1 file changed

+78
-45
lines changed

‎README.md

+78-45
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,35 @@
1-
# express-fileupload
2-
Simple express file upload middleware that wraps around [connect-busboy](https://github.com/mscdex/connect-busboy).
1+
# Description
2+
Simple express middleware for uploading files.
33

4-
## Install
4+
# Install
55
```bash
6-
npm install express-fileupload
7-
```
6+
# With NPM
7+
npm install --save express-fileupload
88

9-
## Important Note
10-
Add `app.use(fileUpload())` *AFTER* `app.use(bodyParser.json)` and any other bodyParser middlewares! This limitation will be explored and resolved in an upcoming release.
9+
# With Yarn
10+
yarn add express-fileupload
11+
```
1112

12-
=======
13-
Pass in Busboy options directly to express-fileupload (using Busboy `v0.2.13`). Check out the Busboy documentation here: https://github.com/mscdex/busboy#api
13+
# Usage
14+
When you upload a file, the file will be accessible from `req.files`.
1415

16+
### Example Scenario
17+
* You're uploading a file called **car.jpg**
18+
* Your input's name field is **foo**: `<input name="foo" type="file" />`
19+
* In your express server request, you can access your uploaded file from `req.files.foo`:
1520
```javascript
16-
app.use(fileUpload({
17-
limits: { fileSize: 50 * 1024 * 1024 },
18-
}));
21+
app.post('/upload', function(req, res) {
22+
console.log(req.files.foo); // the uploaded file object
23+
});
1924
```
25+
The **req.files.foo** object will contain the following:
26+
* `req.files.foo.name`: "car.jpg"
27+
* `req.files.foo.mv`: A function to move the file elsewhere on your server
28+
* `req.files.mimetype`: The mimetype of your file
29+
* `req.files.data`: A buffer representation of your file
2030

21-
## Example
22-
23-
### Node.js:
24-
31+
### Full Example
32+
**Your node.js code:**
2533
```javascript
2634
var express = require('express');
2735
var fileUpload = require('express-fileupload');
@@ -31,41 +39,66 @@ var app = express();
3139
app.use(fileUpload());
3240

3341
app.post('/upload', function(req, res) {
34-
var sampleFile;
35-
36-
if (!req.files) {
37-
res.send('No files were uploaded.');
38-
return;
39-
}
40-
41-
sampleFile = req.files.sampleFile;
42-
sampleFile.mv('/somewhere/on/your/server/filename.jpg', function(err) {
43-
if (err) {
44-
res.status(500).send(err);
45-
}
46-
else {
47-
res.send('File uploaded!');
48-
}
49-
});
42+
var sampleFile;
43+
44+
if (!req.files) {
45+
res.send('No files were uploaded.');
46+
return;
47+
}
48+
49+
// The name of the input field (i.e. "sampleFile") is used to retrieve the uploaded file
50+
sampleFile = req.files.sampleFile;
51+
52+
// Use the mv() method to place the file somewhere on your server
53+
sampleFile.mv('/somewhere/on/your/server/filename.jpg', function(err) {
54+
if (err) {
55+
res.status(500).send(err);
56+
}
57+
else {
58+
res.send('File uploaded!');
59+
}
60+
});
5061
});
5162
```
5263

53-
### HTML Form:
64+
**Your HTML file upload form:**
5465
```html
5566
<html>
56-
<body>
57-
<form ref='uploadForm'
58-
id='uploadForm'
59-
action='http://localhost:8000/upload'
60-
method='post'
61-
encType="multipart/form-data">
62-
<input type="file" name="sampleFile" />
63-
<input type='submit' value='Upload!' />
64-
</form>
65-
</body>
67+
<body>
68+
<form ref='uploadForm'
69+
id='uploadForm'
70+
action='http://localhost:8000/upload'
71+
method='post'
72+
encType="multipart/form-data">
73+
<input type="file" name="sampleFile" />
74+
<input type='submit' value='Upload!' />
75+
</form>
76+
</body>
6677
</html>
6778
```
6879

69-
## Thanks & Credit
80+
### Using Busboy Options
81+
Pass in Busboy options directly to the express-fileupload middleware. [Check out the Busboy documentation here.](https://github.com/mscdex/busboy#api)
82+
83+
```javascript
84+
app.use(fileUpload({
85+
limits: { fileSize: 50 * 1024 * 1024 },
86+
}));
87+
```
88+
89+
### Available Options
90+
Pass in non-Busboy options directly to the middleware. These are express-fileupload specific options.
91+
92+
Option | Acceptable&nbsp;Values | Details
93+
--- | --- | ---
94+
safeFileNames | <ul><li><code>false</code>&nbsp;**(default)**</li><li><code>true</code></li><li>regex</li></ul> | Strips characters from the upload's filename. You can use custom regex to determine what to strip out. If set to `true`, non-alphanumeric characters _except_ dashes and underscores will be stripped. This option is off by default.<br /><br />**Example #1 (strip out slashes from file names):** `app.use(fileUpload({ safeFileNames: /\\/g }))`<br />**Example #2:** `app.use(fileUpload({ safeFileNames: true }))`
95+
96+
# Known Bugs
97+
##### If you're using bodyParser middleware
98+
Add `app.use(fileUpload())` *AFTER* `app.use(bodyParser.json)` and any other `bodyParser` middlewares! This limitation will be investigated in an upcoming release.
99+
100+
# Help Wanted!
101+
Pull Requests are welcomed!
70102

71-
* [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)
103+
# Thanks & Credit
104+
[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)

0 commit comments

Comments
 (0)