Skip to content

Getting Started

Dus Mamud edited this page Nov 9, 2026 · 1 revision

Getting Started

Install

npm install @dusrel/image

Add only the sub-packages you need — codecs and features are separately installable and their WASM loads lazily:

npm install @dusrel/image-avif @dusrel/image-crop

Process an image

import { processImage } from '@dusrel/image';

const { blob, report } = await processImage(file, {
  format: 'image/webp',   // built in: 'image/jpeg' | 'image/png' | 'image/webp'
  quality: 0.8,           // 0..1 (codec packages use their native scales)
  resize: { width: 1600 },
  crop: { x: 80, y: 60, width: 640, height: 480 },
});

console.log(report.stepsApplied, report.savingsRatio);

Use a WASM codec format (AVIF, JPEG XL, QOI, …)

Formats beyond the canvas three come from the codec packages — register the encoder you installed, and the format becomes available everywhere:

import { processImage } from '@dusrel/image';
import { encode } from '@dusrel/image-avif';

const { blob } = await processImage(file, {
  format: 'image/avif',
  codecs: [{ mimeType: 'image/avif', encode: (d) => encode(d, { quality: 50, speed: 9 }) }],
});

Give a byte budget instead of guessing quality

const result = await processImage(file, {
  format: 'image/webp',
  maxSizeBytes: 200_000,   // the engine searches quality for you
});

console.log(result.targetSizeMet);  // reported honestly — never faked

Compose with the pipeline

import { pipeline, codecPlugin, imageDataPlugin } from '@dusrel/image';
import { encode } from '@dusrel/image-avif';
import { adjust } from '@dusrel/image-adjust';

const { blob } = await pipeline(file)
  .resize({ width: 1200 })
  .use(imageDataPlugin({ name: 'adjust', transform: (d) => adjust(d, { saturation: 0.1 }) }))
  .use(codecPlugin({ mimeType: 'image/avif', encode: (d) => encode(d, { quality: 55 }) }))
  .run();

Crop with the component

<script type="module">
  import { defineCropElement } from '@dusrel/image-crop/element';
  defineCropElement();
</script>

<dusrel-crop src="photo.jpg" aspect="16/9"></dusrel-crop>

The component returns geometry only (natural pixels); feed event.detail.crop into processImage's crop option. React, Vue and Svelte users get typed wrappers — see Framework Integrations.

Using Vite?

Production builds need no configuration. Vite dev pre-bundling can break codec asset URLs — two verified fixes live on the Bundlers and Codec Assets page.

No build step?

See examples/cdn in the repository for an import-map page that runs entirely from CDN modules, or open the live playground.


Next: Core Concepts · Cookbook

Clone this wiki locally