sharp-heic-test

Tiny CLI helper to inspect and convert HEIC/HEIF files with Sharp compiled against libheif.

Prerequisites

• Node.js 18+ (using nvm keeps versions consistent)
• Build toolchain (build-essential on Debian/Ubuntu, Xcode tools on macOS)
• libvips-dev and libheif-dev (or platform equivalents) — required even if we vendor libvips
• Git, curl, Python 3.11+ (for Meson/Ninja helper tooling)

Debian/Ubuntu

sudo apt update
sudo apt install -y build-essential pkg-config libvips-dev libheif-dev

macOS (Homebrew)

brew install vips libheif

Install dependencies

npm install

Compile Sharp with HEIC support

Sharp 0.34 ships with libvips 8.17.3+. Debian bookworm only exposes 8.14, so you need a local build that includes libheif.

1. Build libvips 8.17.3 locally

# run from repo root
python3 -m venv .venv
. .venv/bin/activate
pip install meson ninja
curl -LO https://github.com/libvips/libvips/releases/download/v8.17.3/vips-8.17.3.tar.xz
tar xf vips-8.17.3.tar.xz
mkdir -p vendor/libvips
cd vips-8.17.3
meson setup _build --prefix="$(dirname "$PWD")/vendor/libvips"
ninja -C _build
meson install -C _build
deactivate
rm -rf _build

Feel free to delete the vips-8.17.3 folder and .venv afterwards; the installed files live in vendor/libvips (already ignored via .gitignore).

2. Rebuild Sharp against the freshly built libvips

PKG_CONFIG_PATH="$(pwd)/vendor/libvips/lib/x86_64-linux-gnu/pkgconfig" \
npm_config_sharp_libvips_local="$(pwd)/vendor/libvips" \
npm_config_sharp_prebuilds=false \
npm run sharp:rebuild

Whenever you update libvips/libheif, re-run the command above. The environment variables ensure that sharp links against the vendored libvips instead of the older system copy.

Project structure

• convert.js – CLI entry point. Prints metadata, optionally converts, and includes an elapsed-time summary for quick benchmarks.
• sample1.heif, shelf-christmas-decoration.heic – fixture assets for local testing.
• vendor/libvips – locally compiled libvips with HEIC support (ignored in git).

Verifying the tool locally

1. Install npm dependencies (npm install).

2. Rebuild sharp against the local libvips (section above).

3. Run a metadata-only pass:

   npm run metadata -- ./shelf-christmas-decoration.heic

4. Run a conversion to confirm HEIC decoding end-to-end:

   npm run convert -- ./shelf-christmas-decoration.heic ./output.jpg

   The CLI will print metadata, write the converted file, and emit an Elapsed time: ... line (millisecond precision) so you can track regression or benchmark numbers. Remove output.jpg when done.

Using this repo as a HEIC reference for other projects

This repository is intentionally minimal. Its only purpose is to document the exact steps required to get sharp working with HEIC/HEIF input. To apply the same setup elsewhere:

1. Build libvips 8.17.3+ with libheif exactly as shown above (Meson/Ninja + vendor/libvips). Copy the resulting folder into your real project, or host it on your artifact storage.

2. Reuse the rebuild command in your actual project when installing sharp:

   PKG_CONFIG_PATH="/path/to/vendor/libvips/lib/x86_64-linux-gnu/pkgconfig" \
   npm_config_sharp_libvips_local="/path/to/vendor/libvips" \
   npm_config_sharp_prebuilds=false \
   npm rebuild sharp --build-from-source

3. Smoke-test conversion within that project using any HEIC fixture (you can reuse the two files in this repo or your own assets). If the CLI in your main app prints metadata and converts successfully, libheif support is wired up.

4. Keep system deps documented: whatever environment runs your main app still needs libheif-dev, libvips-dev, build tools, and Node 18+. Use this README purely to remember the build flags/env vars required to make sharp pick up the HEIC-capable libvips.

Operational tips

• output.jpg is git-ignored; delete or overwrite freely during testing.
• To benchmark large batches, wrap the CLI in a shell loop and parse the elapsed-time line.
• If sharp: rebuild fails complaining about libvips, double-check the PKG_CONFIG_PATH and npm_config_sharp_libvips_local env vars, then rerun.

Usage

All commands run from the project root.

Print metadata only

npm run metadata -- ./shelf-christmas-decoration.heic

Convert and print metadata

npm run convert -- ./shelf-christmas-decoration.heic ./output.jpg

Accepted output extensions: jpg, jpeg, png, webp.

During conversion the CLI:

1. Confirms the input file exists
2. Prints key metadata as JSON
3. Writes the converted file to the requested path (creating folders if needed)

Sample assets

Two HEIC/HEIF fixtures are bundled for quick testing:

• shelf-christmas-decoration.heic
• sample1.heif

Try converting both to ensure your Sharp build has HEIC support.

Troubleshooting

• Input file not found: Double-check the path (relative paths are resolved from the project root).
• Output file must use ... extension: Use one of the supported formats listed above.
• Conversion failed: ... libvips-cpp.so: Reinstall libvips/libheif, ensure the vendored libvips exists, and rerun npm run sharp:rebuild.
• Rebuild errors referencing libheif: confirm the system package libheif-dev (or Homebrew equivalent) is installed before compiling libvips.