node package manager

imagekit

NodeJS package that wraps ImageKit.io upload APIs and URL builder logic with easy to use interfaces.

ImageKit.io provides ready-to-use image optimisation servers along with dedicated image storage, global CDN, on-the-fly image transformation like resize, crop, rotate directly from the URL and image uploads.

By using ImageKit, you can experience about 30% improvement in page load time thanks to the tons of image optimizations that work out of the box without you putting in any effort. Migrating to ImageKit is super simple and takes just a few minutes with our Plug-and-Play technology. Images are delivered across the globe using a CDN ensuring lightning fast experience for your users.

Installation

npm install imagekit

Sample

var ImageKit = require('imagekit');

var imagekit = new ImageKit({
   "imagekitId" : "demo",       
   "apiKey" : "myapikey",       
   "apiSecret" : "myapisecret", 
});

/*
    Returns
    https://demo.imagekit.io/img/tr:h-100,w-200,cm-resize:b-5_FF0000/default-image.jpg
*/
var url = imagekit.image("default-image.jpg")
              .transform({HEIGHT : 100, WIDTH : 200, CROP_MODE : "resize"})
              .transform({BORDER : "5_FF0000"})
              .url();


/*
    Uploads an image with the name my-image in the folder /images in your storage
 */
var uploadPromise = imagekit.upload(imageAsBase64String, {
                                "filename" : "my-image",
                                "folder" : "/images"
                            });

/*
    Uploads an image by specifying the HTTP URL
 */
var uploadPromise = imagekit.uploadViaURL("http://www.example.com/image.jpg", {
                                "filename" : "my-image",
                                "folder" : "/images"
                            });  
                            
uploadPromise.then(function(resp) {
    //handle upload success here    
}, function(err) {
    //handle upload failure here
});
                            

Initialising the module

var ImageKit = require('imagekit');

var imagekit = new ImageKit({
   "imagekitId" : "demo",         /* required */
   "apiKey" : "myapikey",         /* required */
   "apiSecret" : "myapisecret",   /* required */
   "useSubdomain" : false,
   "useSecure" : false
});

imagekitId (required, String)

The unique ID that is selected by you to uniquely identify your account and images. This can be accessed from the Settings section of your dashboard

apiKey and apiSecret (required, String)

Key pair that is created when you register on ImageKit. The two keys can be accessed from the Settings section of your dashboard

Do not share your API Secret with anyone or any client device.

useSubdomain (optional, Boolean)

Default: false

If set to true, your ImageKit ID will be used as the subdomain of the URL. If your ImageKit ID is demo, then the URL would begin with http://demo.imagekit.io. This works only for paid accounts. If set to false, the ImageKit ID is used in te URL path with the default subdomain http://ik.imagekit.io/demo.

useSecure (option, Boolean)

Default: false

If set to true uses https protocol for the the generated image fetch URLs. Default is http protocol for image fetch URLs. This setting impacts only the image fetch URLs. Image upload is done over https internally.

Creating image URLs and HTML

An image instance has to be created before it can be subject to transforms or turned into a URL or HTML. The image instance is made up of the image name that has to be fetched and other optional parameters.

  /* without optional params */
  var img = imagekit.image('default-image.jpg');

  /* with optional params */
  var img = imagekit.image('default-image.jpg', { "pattern" : "image" });

Optional parameters for image instance

pattern Default : "img"

The URL pattern which has to be used to fetch the image. URL patterns help identify the original sources of the image. You can read more about patterns and sources in ImageKit Documentation

Transforms in image URL

All transforms that are available in ImageKit can be added by using the transform function. The transform function works on an image instance.

Input to transform function is a key-value map with the transformation name as the key against the transformation value. Transformation name is passed in capital letters.

  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100});

The transformation names are as follows

HEIGHT, WIDTH, QUALITY, CROP, CROP_MODE, FOCUS, FORMAT, ROUDED_CORNER, BORDER, ROTATION, BLUR, NAMED, OVERLAY_IMAGE, OVERLAY_X, OVERLAY_Y, OVERLAY_FOCUS, BACKGROUND, PROGRESSIVE, COLOR_PROFILE, METADATA

The documentation for these transformations can be found at ImageKit Documentation.

Chained transformations can be obtained by chaining calls to transform function

  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100})
                    .transform({BORDER : "10_FF0000"})
                    .transform({ROTATE : 90})

Output

The image instance or its transform can be used to generate the image URL or HTML with or without signature

URL

.url() function

  //generates an unsigned image URL.
  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100})
                    .url();

Signed URL

.signedUrl() generates a signed URL of the image. Read more about Signed URLs here. The function optionally accepts the expiry time in seconds after which the image URL will get expired. If no expiry time is specified then the signed URL does not expire (theoretically it does expire after an infinite time). Security using signatures can be enabled from your dashboard settings.

  //generates a URL that expires after 300 seconds and doesn't allow transformations to be changed
  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100})
                    .signedUrl(300);

HTML with unsigned URL

.html() function gives the image tag with the unsigned URL. It optionally accepts an object where you can specify the id and the className to be given to the HTML tag. By default, id and className are considered empty.

className is a string which can contain multiple class names. Each class name is separated by a space

  //generates an HTML tag
  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100})
                    .html({id : "my-image", className : "class1 class2 class3"});

HTML with signed URL

.signedHtml() is same as the .html() function except that it uses the signed URL for the image and to generate the signed URL accepts an additional optional parameter expirySeconds

  //generates an HTML tag
  var img = imagekit.image('default-image.jpg')
                    .transform({HEIGHT: 200, WIDTH: 100})
                    .html({id : "my-image", className : "class1 class2 class3", expirySeconds : 300});

By default, if expirySeconds is not specified, then the signed URL does not expire

Uploading Images using base64

Images can be uploaded to your ImageKit Media Library using the .upload() function. The .upload() function accepts two arguments - the image to be uploaded and an additional object with different upload options.

The image to be uploaded should be passed as a base64 encoded string.

var ImageKit = require('imagekit');

var imagekit = new ImageKit({
   "imagekitId" : "demo",       
   "apiKey" : "myapikey",       
   "apiSecret" : "myapisecret", 
});

/*
    Uploads an image with the name my-image in the folder /images in your storage
 */
var uploadPromise = imagekit.upload(imageAsBase64String, {
                                "filename" : "my-image",
                                "folder" : "/images"
                            });
                            
uploadPromise.then(function(resp) {
    //handle upload success here    
}, function(err) {
    //handle upload failure here
});
                            

Uploading Images using remote HTTP URL

Images can be uploaded to your ImageKit Media Library using the .uploadViaURL() function. The .uploadViaURL() function accepts two arguments - the remote HTTP URL of the image to be uploaded and an additional object with different upload options.

var ImageKit = require('imagekit');

var imagekit = new ImageKit({
   "imagekitId" : "demo",       
   "apiKey" : "myapikey",       
   "apiSecret" : "myapisecret", 
});

/*
    Uploads an image by specifying the HTTP URL
 */
var uploadPromise = imagekit.uploadViaURL("http://www.example.com/image.jpg", {
                                "filename" : "my-image",
                                "folder" : "/images"
                            });
                            
uploadPromise.then(function(resp) {
    //handle upload success here    
}, function(err) {
    //handle upload failure here
});
                            

Upload Options

filename (String, required)

The name with which the file has to be uploaded. You should inculde the file extension in the filename field.

useUniqueFilename (Boolean, optional)

Default value is true.

Setting this field to true, adds a unique alphanumeric string at the end of the filename specified in the previous field (and before the file extension), to ensure that even if you already have a file with the same name in your media library, you don't override it accidentally.

folder (String, optional) Default: "/"

Used to specify the folder in which the file has to be uploaded. By default it will be uploaded in the root of your media library. Folder names are relative to the root "/". For example if you want to upload the image in files folder of your media library, then the value of this parameter should be /files.

  var uploadPromise = imagekit.upload(<base64ImageString>, {
      "filename" : 'mysampleimage.jpg',
      "folder" : "/images"
  });

Both .upload() and .uploadViaURL() function returns a Promise that will be resolved on successful upload and rejected on any error (validation or server errors).

Successful upload output

{
  "imagePath": "images/mysampleimage_BJyuWdf0.jpg",
  "size": 51198,
  "height": 300,
  "width": 444
}

The size is in bytes and height and width are in pixels. You can use the value of imagePath and use the .image() function of the SDK (mentioned above) to get the image URL as per requirement. The image is accessible immediately after upload.

Failed upload

{
  "exception": true,
  "statusNumber": 1400,
  "statusCode": "BAD_REQUEST",
  "message": "Invalid file format"
}

You can read about the various statusNumbers and statusCodes in case of upload failure in the Upload Documentation. Apart from the generic status codes for upload, the SDK sends the following status codes in case validation or error occurs at SDK level itself.

Status Codes Status Number Meaning
BAD_REQUEST 2400 Missing filename, ImageKit ID, API Secret or Key during upload
SERVER_ERROR 2500 Internal error while sending out upload request

Working Demo

A working demo for image fetch and upload is available in the demo folder. Run npm install in the root folder. Then in demo folder, in the file server.js update the module initialization parameters - ImageKit ID, API Key and Secret. These parameters can be obtained from your ImageKit dashboard after sign up.

The demo server creates two routes - a sample page accessible at http://localhost:3456/demo-page.html to test image fetch and a POST api route /rest/api/upload that accepts a single file in the parameter image and uploads it to /images folder.

Change Log

Version 1.0.7

Added support for new transforms in the URL like color profile, progressive JPEG, metadata, background.

Version 1.0.8

Fix the base URL for image upload

Version 1.1.0

Use the updated signature-related query parameters

Version 1.2.0

Added support for upload image via remote HTTP URL