blueimp-file-uploader-express
Version:
This is a File Uploader for Node.js, the project is based on Blueimp jQuery File Upload developed by Sebastian Tschan.
282 lines (232 loc) • 8.93 kB
Markdown
Blueimp file uploader for Express js
====================================
[](https://travis-ci.org/vihuvac/blueimp-file-uploader-express) [](https://gitter.im/vihuvac/blueimp-file-uploader-express?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [](https://github.com/vihuvac/blueimp-file-uploader-express/blob/master/LICENSE)
[](https://nodei.co/npm/blueimp-file-uploader-express/)
A simple express module for integrating the *[jQuery File Upload](http://blueimp.github.io/jQuery-File-Upload/)* frontend plugin.
## Contents
* [History](#history)
* [Installation](#installation)
* [Configuration](#configuration)
* [Usage with options](#usage-with-options)
* [SSL Support](#ssl-support)
* [Multiple thumbnails](#multiple-thumbnails)
* [Tests](#tests)
* [Contributions](#contributions)
## History
The code was forked from a sample backend code from the [plugin's repo](https://github.com/blueimp/jQuery-File-Upload/wiki/Setup). Adaptations were made to show how to use this plugin with the popular *[Express](http://expressjs.com/)* *Node.js* framework.
Although this code was initially meant for educational purposes, enhancements were made. Users can additionally:
* upgrade lwip to version 0.0.6 or higher to support gif images.
* choose the destination filesystem, local or cloud-based *Amazon S3*.
* create thumbnail without heavy external dependencies using [lwip](https://www.npmjs.com/package/lwip).
* setup server-side rules by [configuration](#Configuration).
* modify the code against a [test harness](#Tests).
## Installation
Setup an *Express Project* and install the package.
```js
$ npm install blueimp-file-uploader-express --save
```
## Configuration
```js
options = {
tmpDir: __dirname + "/public/tmp", // tmp dir to upload files to
uploadDir: __dirname + "/public/files", // actual location of the file
uploadUrl: "/files/", // end point for delete route
maxPostSize: 11000000000, // 11 GB
minFileSize: 1,
maxFileSize: 10000000000, // 10 GB
acceptFileTypes: /.+/i,
inlineFileTypes: /\.(gif|jpe?g|png)/i,
imageTypes: /\.(gif|jpe?g|png)/i,
copyImgAsThumb: true, // required
imageVersions: {
maxWidth: 200,
maxHeight: 200
},
accessControl: {
allowOrigin: "*",
allowMethods: "OPTIONS, HEAD, GET, POST, PUT, DELETE",
allowHeaders: "Content-Type, Content-Range, Content-Disposition"
},
storage: {
type: "local", // local or aws
aws: {
accessKeyId: "xxxxxxxxxxxxxxxxx", // required if aws
secretAccessKey: "xxxxxxxxxxxxxxxxxxxxxxx", // required if aws
region: "sa-east-1", // make sure you know the region, else leave this option out
bucketName: "xxxxxxxxx", // required if aws
path: "some-directory-in-your-bucket/" // optional if aws
}
}
};
```
### Usage with options
```js
// config the uploader
var options = {
tmpDir: __dirname + "/../public/uploaded/tmp",
uploadDir: __dirname + "/../public/uploaded/files",
uploadUrl: "/uploaded/files/",
maxPostSize: 11000000000, // 11 GB
minFileSize: 1,
maxFileSize: 10000000000, // 10 GB
acceptFileTypes: /.+/i,
// Files not matched by this regular expression force a download dialog,
// to prevent executing any scripts in the context of the service domain:
inlineFileTypes: /\.(gif|jpe?g|png)/i,
imageTypes: /\.(gif|jpe?g|png)/i,
copyImgAsThumb: true, // required
imageVersions: {
maxWidth: 200,
maxHeight: 200
},
accessControl: {
allowOrigin: "*",
allowMethods: "OPTIONS, HEAD, GET, POST, PUT, DELETE",
allowHeaders: "Content-Type, Content-Range, Content-Disposition"
},
storage: {
type: "aws",
aws: {
accessKeyId: "xxxxxxxxxxxxxxxxx",
secretAccessKey: "xxxxxxxxxxxxxxxxx",
region: "sa-east-1", // make sure you know the region, else leave this option out
bucketName: "xxxxxxxxxxxxxxxxx"
}
}
};
// Init the uploader
var uploader = require("blueimp-file-uploader-express")(options);
module.exports = function (router) {
router.get("/upload", function (req, res) {
uploader.get(req, res, function (err, obj) {
res.send(JSON.stringify(obj));
});
});
router.post("/upload", function (req, res) {
uploader.post(req, res, function (err, obj) {
res.send(JSON.stringify(obj));
});
});
/**
* The path SHOULD match options.uploadUrl
*
* If you are using the optional parameter path: for aws, you need to pass the reference before the file name, e.g:
* router.delete("/uploaded/files/:directory/:name", function (req, res) {}
*
* Otherwise just pass a single reference, e.g:
* router.delete("/uploaded/files/:name", function (req, res) {}
*/
router.delete("/uploaded/files/:name", function (req, res) {
uploader.delete(req, res, function (err, obj) {
res.send(JSON.stringify(obj));
});
});
return router;
}
```
> **Note**:
>
> You can use the optional parameter ```path``` in order to store images in that specific directory.
### SSL Support
Set the `useSSL` option to `true` to use the package with an [HTTPS server](http://expressjs.com/4x/api.html#app.listen).
```js
var express = require("express"),
fs = require("fs"),
https = require("https"),
app = express()
;
// config the uploader
var options = {
...
useSSL: true
...
};
// init the uploader
var uploader = require("blueimp-file-uploader-express")(options);
app.get("/upload", function(req, res) {
uploader.get(req, res, function (err,obj) {
if(!err)
res.send(JSON.stringify(obj));
})
app.post("/upload", // ...
app.delete("/uploaded/files/:name", // ...
// create the HTTPS server
var app_key = fs.readFileSync("key.pem");
var app_cert = fs.readFileSync("cert.pem");
https.createServer({key: app_key, cert: app_cert}, app).listen(443);
```
### Multiple thumbnails
To generate multiple thumbnails while uploading.
```js
var options = {
tmpDir: __dirname + "/../public/uploaded/tmp",
uploadDir: __dirname + "/../public/uploaded/files",
uploadUrl: "/uploaded/files/",
copyImgAsThumb: true, // required
imageVersions: {
maxWidth: 200,
maxHeight: 200
},
storage: {
type: "local"
}
};
```
`copyImgAsThumb` needs to be set to true. `imageVersions`, `maxWidth` and `maxHeight` will by default create a `thumbnail` folder and place the specified width/height thumbnail in it.
Optionally, you can omit the `maxHeight`. In this case, it will be resize proportionally to the specified width.
```js
imageVersions: {
maxWidth: 200
},
```
also
```js
imageVersions: {
maxWidth: 200,
maxHeight : "auto"
},
```
PS : `auto` value works only with height.
You can also specify multiple thumbnail generations like
```js
var options = {
tmpDir: __dirname + "/../public/uploaded/tmp",
uploadDir: __dirname + "/../public/uploaded/files",
uploadUrl: "/uploaded/files/",
copyImgAsThumb: true,
imageVersions: {
maxWidth: 200,
maxHeight: "auto",
"large" : {
width : 600,
height : 600
},
"medium" : {
width : 300,
height : 300
},
"small" : {
width : 150,
height : 150
}
},
storage: {
type: "local"
}
};
```
Refer to : [How to submit additional form data](https://github.com/blueimp/jQuery-File-Upload/wiki/How-to-submit-additional-form-data) to send additional form data from the client.
## Tests
Unit tests can be run with *Jasmine* using `npm test` or this command:
```js
$ jasmine-node specs/
```
## Contributions
Changes and improvements are welcome! Feel free to fork and open a pull request.
### To Do
* Make [Configuration](#configuration) documentation clearer and shorter.
* Refactor code to build tests and provide generic transports as in `winston`.
* Write end to end tests with [WebdriverIO](http://webdriver.io/).
* Provide a basic image processing pipeline (resizing, croping, filter effects).
* Fix AWS thubnail issue (preview at uploading).
* Provide access to other cloud-based services like *Microsoft Azure*.