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)
const imgbbUploader = require("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 fileimageUrl
in case of an URL stringbase64string
in case of base64-encoded image
const imgbbUploader = require("imgbb-uploader");
const options = {
apiKey: process.env.IMGBB_API_KEY,
imagePath: "./your/image/path",
name: "yourCustomFilename",
expiration: 3600 ,
imageUrl: "https://placekitten.com/500/500",
base64string:
"iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEklEQVR42mNcLVNbzwAEjDAGACcSA4kB6ARiAAAAAElFTkSuQmCC",
};
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");
const data = "definitely-not-an-image-binary";
const bufferToBase64 = (buffer) =>
new Promise((resolve) => {
const buff = new Buffer(buffer);
const base64string = buff.toString("base64");
return setTimeout(() => {
resolve(base64string);
}, 1000);
});
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
1.5.0
ESM support 🚀
While trying to utilise the initial version of phraze module, a sudden realization shocked me. There are people out there who are writing pure ESM nodejs projects, and they do it as it is the most natural thing to do !!!
Despite having fairly painful memories of the UMD (universal module definition) / AMD (asyncronous module definition) / ESM (EcmaScript Modules) / CJS (CommonJS) jungle, I tried to give it another go.
Long story short, it's still far from obvious, but now things are a bit simpler that they once were. ESM seem to have won the heart of the many (in the frontend, it had mine already), on top of being anointed by the holy tc39 by definition.
The main difficulties I've encountered while working on ESM support were:
- TS being bitchy about the export syntax. To be able to keep the "require" syntax everyone loves, I had to use a little hack
- Tests duplication. There was no way I'd rewrite & maintain 30+ more tests. So I made an utility that write those tests for me, and that was very fun! 10/10 would write JS with JS again
For the record, this is the 3rd iteration; before that I had a sweet (but hard to maintain) AWK version, then a glitchy awk-in-js one. - jest experimental ESM support. Had several back & forth with babel & ts-jest configs before having a working setup. Fortunately, the size of Jest community, and the quality of it's issue contributors, made it so I could find a working setup without having to dive into their source code. Thanks guys !
Ditch remap-istanbul
GitHub was very annoying flagging me for security issues about this thing absolutely no one interacts with besides me, but yeah. While I had to update Jest to support ESM, I took the chance to ditch it, and generate the coverage report with Jest. Cya remap-istanbul! 👋