vue-image-parser

Universal image rendering engine for Vue 3 — supports JPEG, PNG, WebP, GIF, HEIC, and AVIF with WASM fallback and zero main-thread blocking.

Features

• Format Detection — Binary signature detection (never file extensions) for JPEG, PNG, WebP, GIF, HEIC, HEIF, AVIF
• Capability Probing — Pixel-verified native decode testing to determine browser support
• WASM Fallback — Automatic fallback to libheif-js for HEIC/AVIF on unsupported browsers
• Web Worker Decoding — Decode off the main thread via a pre-spawned worker pool
• EXIF Auto-Orient — Automatic JPEG EXIF orientation handling
• GPU Rendering — Uses ImageBitmap + drawImage for GPU-accelerated canvas rendering
• Vue 3 Integration — useImage composable and <UniversalImage> component
• SSR Safe — All browser APIs guarded for Nuxt/SSR environments
• Tree-Shakable — ESM-only with sideEffects: false

Installation

npm install vue-image-parser

HEIC/AVIF support via libheif-js is included out of the box.

Quick Start

Composable

<script setup>
import { useImage } from 'vue-image-parser'

const { image, loading, error } = useImage('/photos/example.heic')
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">{{ error.message }}</div>
  <canvas v-else ref="canvas" />
</template>

Component

<script setup>
import { UniversalImage } from 'vue-image-parser'
</script>

<template>
  <UniversalImage src="/photos/example.avif" :max-dimension="1024" />
</template>

Plugin (global registration)

import { createApp } from 'vue'
import { ImageParserPlugin } from 'vue-image-parser'

const app = createApp(App)
app.use(ImageParserPlugin)

Programmatic API

import { loadImage, renderImage, detectFormat, disposeEngine } from 'vue-image-parser'

// Load and decode
const decoded = await loadImage('/photo.heic', {
  strategy: 'auto',    // 'auto' | 'native' | 'wasm'
  maxDimension: 2048,
  timeout: 30000,
})

// Render to canvas
const canvas = document.getElementById('canvas') as HTMLCanvasElement
renderImage(canvas, decoded, { fit: 'contain' })

// Detect format without decoding
const format = detectFormat(buffer)

// Clean up when done
decoded.dispose()
disposeEngine()

API Reference

Core Functions

| Function | Description | |----------|-------------| | loadImage(source, options?) | Load and decode an image from URL, File, Blob, or ArrayBuffer | | renderImage(target, image, options?) | Render a decoded image onto a canvas or HTML element | | detectFormat(buffer) | Detect image format from binary signature | | detectFormatFromBlob(blob) | Detect format from a Blob (reads first 64 bytes) | | warmup(formats) | Pre-initialize WASM codecs for given formats | | disposeEngine() | Release all resources (worker pool, codecs, registries) |

LoadOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | strategy | 'auto' \| 'native' \| 'wasm' | 'auto' | Decoding strategy | | signal | AbortSignal | — | Cancellation signal | | timeout | number | 30000 | Timeout in milliseconds | | maxDimension | number | — | Max width/height for downsampling | | maxFileSize | number | 104857600 | Max file size in bytes (100 MB) | | autoOrient | boolean | true | Auto-orient based on EXIF | | onProgress | (p: number) => void | — | Progress callback (0.0-1.0) |

RenderOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | fit | 'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down' | 'contain' | Object-fit behavior | | width | number | image width | Target width | | height | number | image height | Target height | | background | string | — | Background color for letterboxing | | dpr | number | devicePixelRatio | Device pixel ratio |

Utilities

| Function | Description | |----------|-------------| | toDataURL(image, mimeType?) | Convert decoded image to data URL | | toBlobURL(image, mimeType?) | Convert decoded image to blob URL | | toImageBitmap(image) | Convert decoded image to ImageBitmap |

Error Types

All errors extend ImageParserError with a machine-readable code:

| Error | Code(s) | When | |-------|---------|------| | FormatDetectionError | FORMAT_DETECTION_FAILED | Unrecognized binary signature | | CodecError | DECODE_FAILED, HEIC_DECODE_FAILED, AVIF_DECODE_FAILED | Decode failure | | FetchError | FETCH_FAILED, FILE_TOO_LARGE | Network or file size error | | TimeoutError | FETCH_TIMEOUT | Operation exceeded timeout | | AbortError | ABORTED | Cancelled via AbortSignal | | WorkerError | WORKER_CRASHED | Web Worker failure |

Supported Formats

| Format | Native | WASM Fallback | |--------|--------|---------------| | JPEG | All browsers | — | | PNG | All browsers | — | | GIF | All browsers | — | | WebP | All modern browsers | — | | HEIC/HEIF | Safari 17+ | libheif-js | | AVIF | Chrome 85+, Firefox 93+ | libheif-js |

Browser Compatibility

• Chrome 85+
• Firefox 93+
• Safari 16.4+ (OffscreenCanvas)
• Edge 85+

Older browsers work with reduced functionality (main-thread decoding, no OffscreenCanvas).

Memory Management

Decoded images hold GPU resources (ImageBitmaps) and pixel buffers. Always dispose them when done:

const decoded = await loadImage('/photo.heic')
try {
  renderImage(canvas, decoded)
} finally {
  decoded.dispose()
}

In long-lived apps (SPAs), call disposeEngine() when your image-handling view is torn down to release the worker pool and codec instances:

import { onBeforeUnmount } from 'vue'
import { disposeEngine } from 'vue-image-parser'

onBeforeUnmount(() => {
  disposeEngine()
})

The useImage() composable handles disposal automatically on component unmount.

Error Handling

All errors extend ImageParserError with a machine-readable code for programmatic handling:

import { loadImage, ImageParserError, ErrorCodes } from 'vue-image-parser'

try {
  const decoded = await loadImage(url)
} catch (error) {
  if (error instanceof ImageParserError) {
    switch (error.code) {
      case ErrorCodes.FORMAT_DETECTION_FAILED:
        console.warn('Unsupported image format')
        break
      case ErrorCodes.FETCH_TIMEOUT:
        console.warn('Image took too long to load')
        break
      case ErrorCodes.FILE_TOO_LARGE:
        console.warn('Image exceeds size limit')
        break
      default:
        console.error('Image error:', error.message)
    }
  }
}

SSR / Nuxt

All browser APIs are guarded behind isBrowser() checks. Use onMounted() or <ClientOnly> to defer image operations:

<script setup>
import { onMounted } from 'vue'
import { loadImage } from 'vue-image-parser'

onMounted(async () => {
  const decoded = await loadImage('/photo.heic')
  // ...
})
</script>

Contributing

Contributions are welcome! Please read the Contributing Guide and Code of Conduct before submitting a PR.

License

MIT