There are times on your website when you want to allow users to upload content from their local drive to your server e.g. user profile pictures. In this post I will show you how to do this using node.js, Express and jquery.

A fully functional example is available on my github account Note: You will have to follow the instructions below after fetching the code to install Express and all of it’s dependencies.

Creating your webserver - Express

Express is a web framework build on top of node. It provides functionality such as creating a webserver to handle network requests to your app, view rendering, static file serving etc. In this post we will use it as our webserver to host our client html file and also handle the file uploads to the server.

To install express, we will use NPM, a package manager for node. From the command line (after installing npm), run the following command:

npm install express

After this completes you will have a node_modules folder and inside that the express node module folder. To create your new express app, run:

node_modules/express/bin/express [the_name_of_your_app] e.g. upload-example-app

Express will then create the application skeleton, an app file, folders for static content etc. The final step is to make sure you have all of the dependencies Express relies on. Change to your applications folder and run:

npm install -d

Now we should be ready to run the server, simply type (I am assuming you have node installed :) ): node app.js, you then have a webserver listening on port 3000, you can view it in your browser at http://localhost:3000

The webpage

In HTML, we can specify an input element with a type of “file”, this then causes the browser to show an upload button that the user can use to choose a file from their computer. The upload buttons visual appearance is dependent on the browser you are using. I’m not going to talk about how you can style this button, but it can be done: http://www.clipboard.com/clip/LQtdg6YHzcYKLyZbAkF5hASUu7kvuDya_ZLe

Our example HTML page will have the basic structure:

Go ahead and create this file under the public folder in your express app, e.g. public/index.html

Limitations

The title of this post has the word “asynchronous” in it, the default implementation of the file input element causes a page reload when the form in submitted, it is not possible to use an AJAX request i.e. XmlHttpRequest, to upload the file to the server. In order to be able to upload a file to the server without causing a page reload you need to perform some browser trickery using hidden iframes, textareas and a sprinkling of magic. Luckily for us there is a jquery plugin we can use that will hide all of this trickery from us, it’s called jquery.form. Download the JavaScript file to your /public/javascripts directory and include the jquery library in your page (good developers will make sure they serve a minified and zipped version of these files), we will also add a javascript file that will contain all of our file upload specific code (upload.js)

We also need a way to initiate the upload of the file to the server, we could add another button to our page, so the user would first choose the file, then click on the upload button, but that seems kind of lazy, so what I do here is to add a setInterval call, that is continually checking the value of the input element, once it has a value we can assume the user has selected a file and we kick off the upload.

jquery.form

Using the jquery.form plugin is pretty simple, we’ll add a submit handler to our form, using jquery, then on the submit event, we use the jquery.form plugin to submit the form asynchronously.

In order for this to work correctly, we need to make sure the form enctype field is set and the action attribute points to our API end point on the server, so our final HTML looks like:

The code in upload.js is shown below, I haven’t filled in the success handler, we will do that once we have implemented the server side part of the code:

Server Side

Now we have the client side code, we need to implement the server code which will handle uploads to the /api/photos API. If we open app.js in your express app folder, we need to define a route for the API call and a handler. Express makes file uploads amazing easy, when you define the handler function, it has two parameters, req and res, which are the HTTP request and response objects. In our HTML we defined an input element named userPhoto, on the req object there is a files field that contains an object with information about all of the files that were uploaded. If we look at req.files we will see that Express has retrieved all of the uploaded data and saved it to a file in the /tmp directory. Using:

app.post('/api/photos', function(req, res) {
    console.log(JSON.stringify(req.files));
});

We see the following information printed to the console where we started our server:

{
    "userPhoto": {
        "size": 4668071,
        "path": "/tmp/f0c99fe2d93f1d0268acbe90c5d16c8a",
        "name": "_DSC7471.jpg",
        "type": "image/jpeg",
        "lastModifiedDate": "2012-02-27T01:52:15.763Z",
        "_writeStream": {
            "path": "/tmp/f0c99fe2d93f1d0268acbe90c5d16c8a",
            "fd": 11,
            "writable": false,
            "flags": "w",
            "encoding": "binary",
            "mode": 438,
            "bytesWritten": 4668071,
            "busy": false,
            "_queue": [],
            "drainable": true
        },
        "length": 4668071,
        "filename": "_DSC7471.jpg",
        "mime": "image/jpeg"
    }
}

For this sample app, I’m just going to move the image from the /tmp directory to the /public/images folder so that we can access the file via an URL. The response we send back to the client will be the path to the image. Note: It is your responsibility to delete the files in the /tmp directory in the request handler, Express will not delete these files once they have been created, don’t forget otherwise your server will mysteriously run out of hard disk space eventually.

Our final server side handler code is shown below, it’s just moving the file and returning the path to the client:

Back on the client side we, we now add the code to our success handler to show the image we uploaded on the page. Note, even though the function is called success, we still need to check for the error parameter that might exist if there was a problem on the server:

IE8 - sheeeeeeeeeeeeeeeeeeeeeeeeeeeeeet

Awesome, we’re all done, time to do a git push, high fives around the office and go home like a hero … but wait, there is that heavy feeling in your stomach, you should really test this in IE8, you don’t want to, but the good dev in you makes you fire up IE8 and test the code. Nearly everything works, but after you upload the data IE8 will open a save file dialog to save the response of the server, sigh (at least it was for me, your milage may vary.

To work around this annoyance, I had to change the response datatype to ‘text’ instead of JSON, you can do this by passing a ‘dataType’: ‘text’ field in the options object we pass to the ajaxSubmit method in the client code. Then on the server side, when calling res.send(), stringify the response e.g. res.send(JSON.stringify({ path: ‘foo/img.jpg’})); and finally before sending back the data using res.send, set the content type to be text/plain i.e. res.contentType(‘text/plain’)

Obviously now in the client code, instead of the response parameter being a JSON object it is a string, so we have to turn it back into a JSON object, using something like jqueries parseJSON method.

Further improvements

For production level code, make sure you:

• Limit the size of the uploads you permit (if applicable). In production you are probably using something like nginx as a frontend webserver proxying to node, so you can set limits in your nginx.conf file
• Never trust content users upload, make sure files that are uploaded are an expected type and don’t give the files more permissions than absolutely necessary