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 )
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.4.0
Sorry for the wait! It was partially caused by a massive amount of yak shaving around Chevereto CI, like, writing a pure Docker stack, then switching to handmade docker-compose, then to remotely-hosted K(uwu)bernetes stack, all while knowing overall little about Docker & nothing about K(uwu)be
"TDD is a time gain, not a time loss", they said !!!
Well, maybe it's not wrong in the end. Afterall the back and forth allowed me to learn important things about TLS and networks and stuff. And there's no debate about the future developments/bugfixes being made easier!
Some other things that took time was hesitating on the interface. In the end I opted for something that felt balanced between TypeScript constraints, flexibility and ease of use.
I hope Chevereto users will like it, whatever the version they're using! Either way I'm all ears for feedback.
- Switch from Travis CI to Github Actions
Travis CI today is far from the one I once knew and loved. No hard feelings, but I have to move away to a more OSS-friendly solution. I went with GitHub Actions. For my limited usage it feels like the old Travis: a free, easy to setup, pleasant to use automation solution.
Maybe one day I'll also automate the npm publish
stuff with it, seems simple enough.