stelluna-image-converter

MIT License Zero required dependencies No build step ~5 KB

The exact image-conversion code behind stelluna.io/image-converter, extracted into a small, framework-agnostic library. Converts JPG, PNG, WEBP, AVIF, and HEIC entirely in the visitor's browser — nothing is uploaded anywhere. Drop it into your own site or app, free.

Download .zip View index.js Live example

Install

No npm required — just download index.js above and import it directly:

<script type="module">
  import { convertImage } from "./index.js";
</script>

Usage

import { convertImage, validateFile, formatBytes } from "./index.js";

const file = document.querySelector('input[type="file"]').files[0];

const error = validateFile(file); // null, "file-too-large", or "unsupported-format"
if (!error) {
  const { blob, width, height } = await convertImage(file, "webp"); // 'jpeg' | 'png' | 'webp' | 'avif'
  console.log(`Converted to ${formatBytes(blob.size)}, ${width}x${height}`);

  const a = document.createElement("a");
  a.href = URL.createObjectURL(blob);
  a.download = "converted.webp";
  a.click();
}

HEIC/HEIF input

Browsers can't decode HEIC natively, so converting a HEIC/HEIF file needs the optional peer dependency heic2any (MIT licensed). If you never pass in a HEIC file, you don't need to install it — it's only imported dynamically when one is:

npm install heic2any

API

Export	Signature	Description
`convertImage`	`(file, targetFormat) => Promise<{blob, width, height}>`	Converts a File/Blob to the target format
`validateFile`	`(file, opts?) => string \| null`	Returns an error code, or `null` if valid
`canEncode`	`(format) => Promise<boolean>`	Whether the current browser can encode that format
`isHeic`	`(file) => boolean`	Detects HEIC/HEIF by MIME type or extension
`detectSourceLabel`	`(file) => string`	Short label like `"HEIC"`, `"PNG"`
`formatBytes`	`(bytes) => string`	e.g. `"1.4 MB"`
`TARGET_FORMATS`	`string[]`	`['jpeg','png','webp','avif']`

What's in the download

index.js — the library, ~150 lines, fully commented
example.html — a working demo, open it directly in a browser, no server needed
README.md — full usage docs
LICENSE — MIT

License

MIT — use it in personal or commercial projects, modify it, ship it, no attribution required (though it's always appreciated).

← Try the live tool at stelluna.io/image-converter