heic-to

heic-to is a browser-side JavaScript library for converting Apple’s HEIC/HEIF images into web-friendly JPEG, PNG, or bitmap formats without any server round-trip. It wraps a WebAssembly build of libheif, and the project’s explicit goal is to track upstream libheif releases closely so newly captured HEIC files keep decoding correctly.

Beyond conversion, it ships an isHeic helper to detect HEIC files before processing, and offers dedicated entry points for tricky environments: a heic-to/csp build for strict Content-Security-Policy setups that forbid unsafe-eval, a heic-to/next build for calling it inside web workers, and an IIFE bundle for direct use from a CDN.

What You Get

• A heicTo function that converts a HEIC/HEIF blob to JPEG, PNG, or bitmap
• An isHeic helper to detect HEIC files before attempting conversion
• Adjustable output quality and bitmap image-orientation options
• A CSP-friendly build (heic-to/csp) that avoids unsafe-eval
• A web-worker build (heic-to/next) and an IIFE bundle for CDN use

Common Use Cases

• Previewing iPhone HEIC photos in a browser upload form
• Converting HEIC uploads to JPEG or PNG client-side before sending to a server
• Detecting whether a selected file is HEIC to branch conversion logic

Under The Hood

Architecture - src/index.js exposes isHeic (which inspects the ISO-BMFF brand bytes at offset 8-12 to identify HEIC variants without decoding) and heicTo, which lazily spins up a Web Worker from an inlined worker blob so the heavy libheif decode runs off the main thread. The worker (src/worker.js) drives the WASM libheif build under src/lib/, decodes to raw pixels, then re-encodes to the requested MIME type via canvas/ImageBitmap. Alternate entry points (src/next, the CSP and IIFE variants) reuse the same core with different worker/eval strategies.

Tech Stack - Plain JavaScript with no runtime npm dependencies; the engine is libheif (currently 1.22.2) compiled to WebAssembly via Emscripten, shipped in both standard and no-unsafe-eval variants under src/lib/. The package exports ., ./csp, and ./next subpaths, and the build is produced by a single build script.

Code Quality - The codebase is small and focused, with an emphasis on tracking upstream libheif versions (a documented release-to-libheif mapping table) rather than an extensive automated test suite; correctness is validated primarily through the bundled interactive example. Detection logic is explicit and well-commented.

API Design - The public API is deliberately minimal and ergonomic: await isHeic(file) and await heicTo({ blob, type, quality }) cover the whole surface, returning standard Blobs. Environment-specific concerns (CSP, workers, CDN) are handled by swapping the import path rather than adding configuration, keeping the common case a two-function affair.