imgbb-uploader

imgbb-uploader

Lightweight Nodejs module to upload pictures to imgBB (or other chevereto-based APIs) and get display URLs in response.
Primary use is letting imgBB handle the hosting & serving of images.

Install

npm install imgbb-uploader

Compatibility:

Node >= 8 ( Promises/await ) ESM projects are supported from 1.5 onward Care: this module uses fs under the hood. It WON'T work outside the node environment !

Want to use this client-side? Click here

Formats supported by ImgBB API: .jpg, .png,.bmp,.gif, base64, url.

We also support Chevereto v3 & v4!

Did you know? imgBB is based on Chevereto, a software written by rodber that you can easily host yourself.

To use with Chevereto, click here!

Upload to imgBB with two string params (legacy)

• I) Get a free API key from imgbb ( estimated time ~1 minute )
• II) Put that in an environment variable
• III) imgbbUploader takes exactly two String arguments : your API key, and the path to your image :

const imgbbUploader = require("imgbb-uploader");
/* or use import in ESM projects:
import { imgbbUploader } from "imgbb-uploader"; 
*/

imgbbUploader("your-imgbb-api-key-string", "path/to/your/image.png")
  .then((response) => console.log(response))
  .catch((error) => console.error(error));

.then((response) => console.log(response)) output example :

{
  id: '26Sy9tM',
  title: '5e7599f65f27',
  url_viewer: 'https://ibb.co/26Sy9tM',
  url: 'https://i.ibb.co/z5FrMR2/5e7599f65f27.png',
  display_url: 'https://i.ibb.co/z5FrMR2/5e7599f65f27.png',
  size: 260258,
  time: '1609336605',
  expiration: '0',
  image: {
    filename: '5e7599f65f27.png',
    name: '5e7599f65f27',
    mime: 'image/png',
    extension: 'png',
    url: 'https://i.ibb.co/z5FrMR2/5e7599f65f27.png'
  },
  thumb: {
    filename: '5e7599f65f27.png',
    name: '5e7599f65f27',
    mime: 'image/png',
    extension: 'png',
    url: 'https://i.ibb.co/26Sy9tM/5e7599f65f27.png'
  },
   medium: {
   filename: '5e7599f65f27.png',
    name: '5e7599f65f27',
    mime: 'image/png',
    extension: 'png',
    url: 'https://i.ibb.co/14kK0tt/5e7599f65f27.png'
  },
  delete_url: 'https://ibb.co/26Sy9tM/087a7edaaac26e1c940283df07d0b1d7'
}

Note about imgBB API: the medium Object will only be returned for .png and base64 files !

With options object (more features, yay! )

From version 1.2.0 onward, you can pass an options object as param.
Use it to customize filename and/or a set duration after which the image will be deleted, cf their docs.

The key you'll use for your image depends on its nature. One of these must be defined:

• imagePath in case of a local file
• imageUrl in case of an URL string
• base64string in case of base64-encoded image

const imgbbUploader = require("imgbb-uploader");
/* or use import in ESM projects:
import { imgbbUploader } from "imgbb-uploader"; 
*/

const options = {
  apiKey: process.env.IMGBB_API_KEY, // MANDATORY

  imagePath: "./your/image/path", // OPTIONAL: pass a local file (max 32Mb)

  name: "yourCustomFilename", // OPTIONAL: pass a custom filename to imgBB API

  expiration: 3600 /* OPTIONAL: pass a numeric value in seconds.
  It must be in the 60-15552000 range.
  Enable this to force your image to be deleted after that time. */,

  imageUrl: "https://placekitten.com/500/500", // OPTIONAL: pass an URL to imgBB (max 32Mb)

  base64string:
    "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEklEQVR42mNcLVNbzwAEjDAGACcSA4kB6ARiAAAAAElFTkSuQmCC",
  // OPTIONAL: pass base64-encoded image (max 32Mb)
};

imgbbUploader(options)
  .then((response) => console.log(response))
  .catch((error) => console.error(error));

This module is tiny & totally unlicensed: to better fit your need, please fork away !
Basic instructions for tweaking

Another example: handling buffer with option object

const imgbbUploader = require("imgbb-uploader");

// Some buffer we need to upload
const data = "definitely-not-an-image-binary";

// Some promise of base64 data
const bufferToBase64 = (buffer) =>
  new Promise((resolve) => {
    const buff = new Buffer(buffer);
    const base64string = buff.toString("base64"); // https://nodejs.org/api/buffer.html#buftostringencoding-start-end
    return setTimeout(() => {
      resolve(base64string);
    }, 1000);
  });

// Some async function
const getDisplayUrl = async (buffer, name = "Default-filename") => {
  return await imgbbUploader({
    apiKey: "definitely-not-a-valid-key",
    base64string: await bufferToBase64(buffer),
    name,
  })
    .then((res) => {
      console.log(`Handle success: ${res.url}`);
      return res.url;
    })
    .catch((e) => {
      console.error(`Handle error: ${e}`);
      return "http://placekitten.com/300/300";
    });
};

const myUrl = getDisplayUrl(data, "Dolunay_Obruk-Sama_<3");

Working with directories/arrays

This module don't and won't directly support array uploads. Only you can pick the best solution for your usecase.
For example, to upload local directories of pictures, I enjoy working with fs.readdir.
I usually create an imagesDir.js file wherever it suits me:

module.exports = require("path").join(__dirname);

Then require that elsewhere and use path.join(imagesDir, relevantSubfolder) to dig into directories.
Once there, iterate using fs.readdir and forEach as needed.

If you need more inspiration Stack Overflow should have you covered!

Contributing

Issues & PRs are very welcome!
Get started with local development

CHANGELOG