# libheif-js

> Emscripten distribution of libheif for Node.JS and the browser

Latest version **1.23.5** (published 2026-10-04) · LGPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install libheif-js
pnpm add libheif-js
yarn add libheif-js
bun add libheif-js
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.23.5 |
| Published | 2026-10-04 |
| First published | 2020-01-17 |
| Weekly downloads | 0 |
| License | LGPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 0 |
| Unpacked size | 8.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 121 |
| Author | Kiril Vatev |
| Maintainers | kirilv |
| Keywords | heif, heic, libheif, decoder, node, browser, emscripten, wasm |

## Links

- npm: https://www.npmjs.com/package/libheif-js
- Repository: https://github.com/catdad-experiments/libheif-js
- Homepage: https://github.com/catdad-experiments/libheif-js#readme
- Issues: https://github.com/catdad-experiments/libheif-js/issues
- npm.io page: https://npm.io/package/libheif-js

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.23.5 (latest) — 2026-10-04
- 1.23.2 — 2026-09-05
- 1.19.8 — 2025-06-12
- 1.18.2 — 2024-10-14
- 1.18.0 — 2024-07-28
- 1.17.1 — 2023-11-08
- 1.15.1 — 2023-02-21
- 1.14.0 — 2022-11-21
- 1.13.0 — 2022-09-12
- 1.12.0 — 2021-06-11
- 1.11.0 — 2021-02-14
- 1.10.0 — 2020-12-16
- 1.9.1 — 2020-09-27
- 1.8.0 — 2020-08-26
- 1.7.0 — 2020-08-21
- … 3 more at https://npm.io/package/libheif-js/versions

## README

# libheif-js

> An Emscripten build of [`libheif`](https://github.com/strukturag/libheif) distributed as an npm module for Node.JS and the browser.

[![github actions test][github-actions-test.svg]][github-actions-test.link]
[![jsdelivr][jsdelivr.svg]][jsdelivr.link]
[![npm-downloads][npm-downloads.svg]][npm.link]
[![npm-version][npm-version.svg]][npm.link]

[github-actions-test.link]: https://github.com/catdad-experiments/libheif-js/actions?query=workflow%3ACI
[github-actions-test.svg]: https://github.com/catdad-experiments/libheif-js/actions/workflows/ci.yml/badge.svg
[npm-downloads.svg]: https://img.shields.io/npm/dm/libheif-js.svg
[npm.link]: https://www.npmjs.com/package/libheif-js
[npm-version.svg]: https://img.shields.io/npm/v/libheif-js.svg
[jsdelivr.svg]: https://img.shields.io/jsdelivr/npm/hm/libheif-js?color=bd33a4
[jsdelivr.link]: https://www.jsdelivr.com/package/npm/libheif-js

This module will respect the major and minor versions of the included `libheif`, with the patch version representing changes in this module itself. For the exact version of `libheif`, please see the [install script](scripts/install.js).

## Install

```bash
npm install libheif-js
```

## Usage

Starting with version 1.17, there are multiple variants of `libheif` that you can use:

* The default is still the classic pure-javascript implementation (for backwards compatibility, of course). You can still bundle this into your project with your bundler of choice.
  ```js
  const libheif = require('libheif-js');
  ```
* There is a `wasm` version available for use in NodeJS. This version will dymanically load the `.wasm` binary at runtime. While you may try to run this through a bundler, you are on your own for making it work.
  ```js
  const libheif = require('libheif-js/wasm');
  ```
* There is also a `wasm` version that is pre-bundled for you, which includes the `.wasm` binary inside the `.js` bundle. You will have a much easier time using this in your browser bundle project.
  ```js
  const libheif = require('libheif-js/wasm-bundle');
  ```

If you'd like to include this module directly into an `html` page using a `<script>` tag, you have the following options:

_Note: in the examples below, make sure to set the latest version when you use it. Always make sure to set a version, to make sure your website does not break unexpectedly when an update is released._

* Use the pure-javascript implementation, exposing a `libheif` global:
  ```html
  <script src="https://cdn.jsdelivr.net/npm/libheif-js@1.23.5/libheif/libheif.js"></script>
  ```
* Use the wasm bundle, exposing a `libheif` global:
  ```html
  <script src="https://cdn.jsdelivr.net/npm/libheif-js@1.23.5/libheif-wasm/libheif-bundle.js"></script>
  ```
* Use the ES Module version, which now works in all major browsers and you should try it:
  ```html
  <script type="module">
    import libheif from 'https://cdn.jsdelivr.net/npm/libheif-js@1.23.5/libheif-wasm/libheif-bundle.mjs';
  </script>
  ```

In all cases, you can use this sample code to decode an image:

```js
const file = fs.readFileSync('./temp/0002.heic');

const decoder = new libheif.HeifDecoder();
const data = decoder.decode(file);
// data in an array holding all images inside the heic file

const image = data[0];
const width = image.get_width();
const height = image.get_height();
```

In NodeJS, you might use this decoded data with other libraries, such as `pngjs`:

```js
const { PNG } = require('pngjs');

const imageData = await new Promise((resolve, reject) => {
  image.display({ data: new Uint8ClampedArray(width*height*4), width, height }, (displayData) => {
    if (!displayData) {
      return reject(new Error('HEIF processing error'));
    }

    resolve(displayData);
  });
});

const png = new PNG({ width: imageData.width, height: imageData.height });
png.data = imageData.data;

const pngBuffer = PNG.sync.write(png);
```

In the browser, you might use this decoded data with `canvas` to display or convert the image:

```js
const canvas = document.createElement('canvas');

canvas.width = width;
canvas.height = height;

const context = canvas.getContext('2d');
const imageData = context.createImageData(width, height);

await new Promise((resolve, reject) => {
  image.display(imageData, (displayData) => {
    if (!displayData) {
      return reject(new Error('HEIF processing error'));
    }

    resolve();
  });
});

context.putImageData(imageData, 0, 0);
```

## Related

This module contains the low-level `libheif` implementation. For more user-friendly functionality, check out these projects:

* [heic-cli](https://github.com/catdad-experiments/heic-cli) - convert heic/heif images to jpeg or png from the command line
* [heic-convert](https://github.com/catdad-experiments/heic-convert) - convert heic/heif images to jpeg and png
* [heic-decode](https://github.com/catdad-experiments/heic-decode) - decode heic images to raw image data

---
_Source: https://npm.io/package/libheif-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._