How to Use Node.js to Upload Files to Alibaba Cloud Object Storage

By Alex Mungai Muchiri, Alibaba Cloud Tech Share Author. Tech Share is Alibaba Cloud’s incentive program to encourage the sharing of technical knowledge and best practices within the cloud community.

Alibaba Cloud Object Storage Service (OSS) is an easy-to-use service that enables you to store, backup and archive large amounts of data on the cloud. OSS acts as an encrypted central repository from where files can be securely accessed from around the globe. OSS guarantees up to 99.9% availability and is a perfect fit for global teams and international project management.

Therefore, if you plan to store large amounts of unstructured data such as audio, images, text, and PDFs, OSS is the right service for you. Alibaba Cloud allows you to login to your Object Storage Service to upload content, organize and also delete unwanted files. The service is accessible through a control panel or through APIs. This tutorial examines how we could use Node.js to upload content to Alibaba Cloud Object Storage Service from a web application.


For you to follow through with this tutorial you will require the following:

  1. Subscribe to the Alibaba Cloud Object Storage Service to get secret access keys.
  2. Run Node.js and npm on your machine. Node.js Downloads contains further information on how to go about Node installation.

In summary, you will require an Alibaba Cloud account, Object Storage Service, Node.js, npm and access keys to your OSS service.

How to Add Access Keys to the Credentials File

To begin with, the Alibaba Cloud OSS supports RESTful API operations and SDKs for most languages. In this tutorial, we are going to use the open-source OSS JavaScript SDK for node.js. We need to first install the ali-oss like so:

Noteworthy, there are two modes that you can choose from; synchronous and asynchronous modes.

To use in synchronous mode, you may additionally use it in conjunction with co. Install co like so:

The asynchronous mode supports callback.

Initializing the Client

This method is applied in the synchronous mode. It involves creating an object app.js like so

On Alibaba Cloud the region field is very important since you had to specify a region ad you subscribed to the OSS service e.g. oss-cn-hangzhou. Here is a complete list of OSS Nodes.

Additionally, there are some endpoints that may not be in the OSS Nodes list, in which case, you should make the following parameters:

  1. secure: to be used in conjunction with region. Access using HTTP if secure is specified to true.
  2. endpoint: when you specify an endpoint, it is alright to ignore the region. Specifying HTTPS for endpoint is allowed.
  3. bucket: It is required that you call the useBucket interface first if the bucket is not specified.
  4. time-out: by default, the value is 60 secs. It is a parameter to specify the OSS API time-out.

Looks all good, now to the next step.

Installing Dependencies

In this step we shall install node.js dependencies so that we can have a directory where our node application will be located. For purposes of this tutorial, we create our app in OSS-node-app like so:

Next, we shall create a package.json file and paste the code below in it:

In the sample above, we have created a package.json file that states the name, version and licence of our app. The scripts parameter enables running of a node server using npm start as opposed to node server.js.

All dependencies that need to be installed will be installed using npm install command. It will then be followed by four dependencies, which will be installed in this project like so

Our dependencies enable us to work with OSS APIs, launch a web server and handle file uploads. The command above also updates the package.json.

  1. ali-OSS — Alibaba SDK for JavaScript to enable us access JavaScript API.
  2. express — Express enables quick and efficient set up of our server.

Our project location and dependencies are all set up, so we can now proceed to fire up our server and set up front-end views. Do note that all dependencies are saved to the package.json file by default in all later Node.js versions.

Creating the Front-end App

We shall begin by creating files for the public views of our application, which is what will be visible by users. We are going to create a public folder using index.html, success.html, and error.html. Our three files shall have the HTML skeleton indicated in the below, only with different content. In all the files, paste the code below:

Proceed to write an error message in the respective file like so:

Proceed to write the success message in the respective file like so:

Now we shall create HTML form with multipart/form-data in the index.html. The form shall have a submit button as well.

Now, we shall create style.css to make the interface easy to read:

We have successfully created the file for uploading, the success and error pages our Node.js application.

Setting Up Server with Express

We are going to wet up a node.js server using the Express framework. To begin with, create a server.js file in the project’s root directory. We then need to use require() to load the four dependencies and then route the app through Express’s app instance like so:

Since the application’s front end is located in the public repository, dependencies configurations shall then set as follows:

Then, proceed to route the three files relative to the server root

Now, we need to set the port to use for listening, in this case 5000 or any other available port

Save this and start the server using npm start.

If you type in http://localhost:5000, in the address bar of your browser, you should be able to access the upload form. Also, try to access http://localhost:5000/success and http://localhost:5000/error to test their response.

Uploading our Files

Our server is all set up, so we shall then integrate our form to ali-oss to enable us upload our first file to the Alibaba OSS.

We need to use new OSS() to connect to the OSS client:

In this first instance, we have a simple local file upload implemented like so:

In a second instance we use the stream upload accessed using the putStream interface. Any objects with an inherent Readable Stream is enabled in this method (both object and network stream). The SDK automatically initiates chunked encoding HTTP PUT when the putStream interface is used.

Uploading object content in the buffer is accessed through the put interface:

If you are uploading a very large file, multipartUpload interface is able to divide a request into smaller executable requests. The advantage of the method is that you only have to upload failed parts as opposed to revising the entire file. Use the parameters below:

  1. name {String}: Object name
  2. file {String|File}: File path or HTML5 Web File
  3. [options] {Object}: Optional parameter
  4. [checkpoint] {Object}: Endpoint checkpoint used in resumable upload. If this parameter is set, the upload starts from the endpoint. If it is not set, the upload restarts.
  5. [partSize] {Number}: Part size
  6. [progress] {Funtion}: A generator function. It contains three parameters:
  7. (percentage {Number}: upload progress (a decimal range from 0 to 1)
  8. (checkpoint {Object}: Endpoint checkpoint
  9. (res {Object}): Response returned after a single part is successfully uploaded
  10. [meta] {Object}: Header meta inforamtion defined by users with a prefix x-oss-meta-
  11. [headers] {Object}: Extra headers. See RFC 2616 for more information.
  12. ‘Cache-Control’: General header used to implement cache mechanisms by specifying a command in HTTP requests and responses. For example: Cache-Control: public, no-cache
  13. ‘Content-Disposition’: Used to indicate the disposition form of a response, which can be an internal reference (a part of a webpage or a page) or an attachment downloaded and saved locally. For example: Content-Disposition: somename
  14. ‘Content-Encoding’: Used to compress data of specific media type. For example: Content-Encoding: gzip
  15. ‘Expires’: Expiration time. For example: Expires: 3600000

The progress parameter above is a calback function to obtain progress of the upload.


Congratulations, you have made it to the end. We have successfully set up an Express application to upload objects to our Alibaba Cloud Object Storage Service (OSS) space! Don’t have an Alibaba Cloud account? Sign up for an account and try over 40 products for free worth up to $1200. Get Started with Alibaba Cloud to learn more.