Bildoptimierung im Browser

jamit-image-optimizer

Eine framework-unabhängige und vollständig typisierte Bibliothek zur Bildoptimierung für Browser-Uploads. Bilder werden lokal skaliert, komprimiert und konvertiert, bevor sie die eigentliche Upload-Pipeline erreichen.

Basierend auf Browser-File-Objekten, Web Workers und WebAssembly, mit Unterstützung für Mixed-File-Batches, kontrollierte Parallelverarbeitung, Zielgrößen-Optimierung und detaillierte Verarbeitungsmetadaten.

Auf npm ansehen Auf GitHub ansehen Demo ausprobieren

Warum das Paket existiert

Bilder optimieren, bevor der Upload beginnt

Große Bilder erhöhen Upload-Zeiten, Bandbreitenverbrauch und Speicherbedarf. jamit-image-optimizer ergänzt eine bestehende Upload-Lösung um eine dedizierte Bildverarbeitung, ohne selbst die Kontrolle über den Upload zu übernehmen.

Das Paket akzeptiert normale Browser-File-Objekte und gibt ebenfalls normale File-Objekte zurück. Dadurch bleibt es mit FormData, Signed URLs, Multipart-Uploads und eigenen Backend-APIs kompatibel.

File-to-File-Verarbeitung

Ein Browser-File wird an den Optimizer übergeben und als Browser-File zurückgegeben, das direkt von einer bestehenden Upload-Pipeline verwendet werden kann.

Lokale Verarbeitung

Bilder werden direkt im Browser dekodiert, skaliert und enkodiert. Das Paket selbst lädt keine Dateien zu einem externen Dienst hoch.

Web Workers

Rechenintensive Bildverarbeitung läuft außerhalb des Hauptthreads, damit die Benutzeroberfläche während der Optimierung reaktionsfähig bleibt.

WebAssembly-Codecs

JPEG-, PNG- und WebP-Verarbeitung basiert auf browserkompatiblen WebAssembly-Codecs, die in den Worker-Build eingebunden sind.

Mixed-File-Batches

Bilder und Nicht-Bilddateien können gemeinsam verarbeitet werden, während die ursprüngliche Reihenfolge der Dateiauswahl erhalten bleibt.

Zielgrößen-Optimierung

Für JPEG- und WebP-Ausgaben kann nach einer geeigneten Qualitätsstufe gesucht werden, wenn eine ungefähre Zieldateigröße erreicht werden soll.

Kontrollierte Parallelverarbeitung

Die Batch-Verarbeitung begrenzt die Anzahl aktiver Bild-Worker, um unnötige CPU- und Speicherbelastung zu vermeiden.

Abbruch und Status-Events

AbortSignal-Unterstützung und Lifecycle-Callbacks ermöglichen das Abbrechen laufender Verarbeitung und die Darstellung sinnvoller Statusinformationen in der UI.

Detaillierte Ergebnisse

Jede Verarbeitung liefert Metadaten zu Original und Ausgabe, Einsparungen, Kompressionsinformationen und Laufzeiten zurück.

Select files

Drop files here

Images are optimized locally. Other file types can remain unchanged in the same batch.

Choose files JPEG · PNG · WebP · native HEIC / HEIF where supported

Optimization settings

Output mode Auto keeps a converted output only when beneficial. Output format Used only in Format mode. Quality JPEG / WebP quality in percent. Target size

KiB

Clear the value to disable target-size optimization. Minimum quality Lower quality limit for target-size search. Max width

Leave empty to disable the width limit. Max height

Aspect ratio is preserved. Concurrency Maximum parallel image-processing jobs.

Klassifizieren

Die Eingabe wird als unterstütztes Bild, nicht unterstütztes Bild oder Passthrough-Datei klassifiziert. Dabei werden MIME-Informationen und, soweit sinnvoll, Dateisignaturen verwendet.

Dekodieren

Unterstützte Bilder werden innerhalb des Workers mit dem passenden Codec oder nativen Browser-Funktionen dekodiert.

Skalieren

Optionale maximale Breiten- und Höhenwerte werden unter Beibehaltung des Seitenverhältnisses angewendet, ohne Bilder unnötig hochzuskalieren.

Enkodieren

Das Bild wird entsprechend dem konfigurierten Output-Modus, Format, der Qualität und einer optionalen Zielgrößen-Strategie enkodiert.

Finalisieren

Der Optimizer entscheidet, ob die erzeugte Ausgabe das Original ersetzen soll, und gibt das finale File zusammen mit detaillierten Metadaten zurück.

pnpm

pnpm add jamit-image-optimizer

npm

npm install jamit-image-optimizer

Das veröffentlichte Paket benötigt keine zusätzlichen Runtime-Abhängigkeiten in der konsumierenden Anwendung. Die vom Worker verwendeten Codecs sind bereits in den Paket-Build eingebunden.

import { optimizeImage } from 'jamit-image-optimizer';

const result = await optimizeImage(file, {
  mode: 'auto',
  quality: 0.85,
  resize: {
    maxWidth: 1920,
    maxHeight: 1920,
  },
});

console.log(result.file);
console.log(result.savings.percent);

Upload-unabhängig

Die bestehende Upload-Implementierung behalten

Der Optimizer sendet selbst keine Dateien. Das zurückgegebene File kann mit FormData, fetch, Axios, Signed URLs, Multipart-Uploads oder einer eigenen Backend-Integration verwendet werden.

const result = await optimizeImage(file, {
  mode: 'auto',
});

const formData = new FormData();

formData.append('file', result.file);

await fetch('/upload', {
  method: 'POST',
  body: formData,
});

import { processFiles } from 'jamit-image-optimizer';

const result = await processFiles(files, {
  mode: 'auto',
  quality: 0.85,
  resize: {
    maxWidth: 1920,
    maxHeight: 1920,
  },
  concurrency: 2,
});

await uploadFiles(result.files);

const result = await processFiles([
  photo,
  contractPdf,
  screenshot,
  video,
]);

for (const item of result.items) {
  console.log({
    name: item.originalFile.name,
    kind: item.kind,
    outcome: item.outcome,
  });
}

original

Originalformat beibehalten

Der Optimizer behält das Ausgangsformat bei, sofern dafür ein Encoder verfügbar ist, und führt Resize oder Kompression ohne absichtliche Formatkonvertierung durch.

const result = await optimizeImage(file, {
  mode: 'original',
  quality: 0.8,
});

format

Explizites Format anfordern

JPEG, PNG oder WebP können gezielt ausgewählt werden, wenn die Anwendung ein bestimmtes Ausgabeformat benötigt.

const result = await optimizeImage(file, {
  mode: 'format',
  format: 'webp',
  quality: 0.85,
});

auto

Vorteilhafte Ausgabe automatisch wählen

Im Auto-Modus wird WebP als Optimierungskandidat geprüft und nur verwendet, wenn die erzeugte Ausgabe tatsächlich einen Vorteil bietet.

const result = await optimizeImage(file, {
  mode: 'auto',
  quality: 0.85,
});

Skalieren ohne das Seitenverhältnis zu verändern

Es kann eine maximale Breite, maximale Höhe oder beides definiert werden. Das Bild wird innerhalb dieser Grenzen verkleinert, ohne absichtliches Upscaling.

const result = await optimizeImage(file, {
  resize: {
    maxWidth: 1920,
    maxHeight: 1920,
  },
});

Auf eine Zielgröße optimieren

Bei qualitätsbasierten Ausgabeformaten kann der Optimizer über eine begrenzte Qualitätssuche versuchen, eine gewünschte Dateigröße zu erreichen und dabei eine definierte Mindestqualität einzuhalten.

const result = await optimizeImage(file, {
  quality: 0.9,
  targetSize: 500 * 1024,
  minQuality: 0.5,
});

console.log(result.compression.targetReached);

Verarbeitungsphasen beobachten

Lifecycle-Updates wie Dekodieren, Skalieren, Enkodieren und Finalisieren können genutzt werden, um sinnvolle Verarbeitungszustände in der Oberfläche anzuzeigen.

await optimizeImage(file, {
  onStatus(status) {
    console.log(status.stage);
  },
});

Laufende Verarbeitung abbrechen

Mit einem AbortSignal kann eine aktive Verarbeitung gestoppt werden. Laufende Worker werden beendet, anstatt unnötig im Hintergrund weiterzuarbeiten.

const controller = new AbortController();

const promise = processFiles(files, {
  concurrency: 2,
  signal: controller.signal,
});

controller.abort();

await promise;

HEIC / HEIF

Native Dekodierung nutzen, wenn der Browser sie bereitstellt

Die Unterstützung für HEIC- und HEIF-Eingaben basiert bewusst auf den nativen Dekodierungsfähigkeiten des Browsers und Betriebssystems. Das Paket bringt keinen eigenen HEVC-Decoder mit.

Wenn die Umgebung die Datei dekodieren kann, kann sie in ein enkodierbares Ausgabeformat wie WebP, JPEG oder PNG konvertiert werden. Ist keine native Dekodierung verfügbar, meldet das Paket den nicht unterstützten Codec-Pfad, anstatt eine Verarbeitung vorzutäuschen.

Ressourcenschutz

Deterministische Verarbeitungslimits definieren

Komprimierte Bilder können beim Dekodieren erheblich mehr Speicher benötigen. Konfigurierbare Grenzen für Eingabegröße, Pixelanzahl und Dimensionen helfen dabei, unerwartet teure browserseitige Verarbeitung zu vermeiden.

const result = await optimizeImage(file, {
  limits: {
    maxInputBytes: 20 * 1024 * 1024,
    maxPixels: 12_000_000,
    maxDimension: 8192,
  },
});

Typisierte Fehler

Fehler über stabile Error-Codes behandeln

ImageOptimizerError stellt typisierte Fehlercodes für Situationen wie ungültige Optionen, nicht verfügbare Codecs, nicht unterstützte Ausgabeformate, überschrittene Ressourcenlimits, Worker-Fehler und abgebrochene Vorgänge bereit.

import {
  isImageOptimizerError,
  optimizeImage,
} from 'jamit-image-optimizer';

try {
  await optimizeImage(file);
} catch (error) {
  if (isImageOptimizerError(error)) {
    console.error(error.code);
    console.error(error.message);
  }
}

Framework-unabhängig

Denselben Core in verschiedenen Frontend-Stacks verwenden

Die öffentliche API besteht aus reinem TypeScript und arbeitet mit Browser-File-Objekten. Vue-, Nuxt-, React-, Next.js-, Svelte- und Vanilla-TypeScript-Anwendungen können dasselbe Paket ohne framework-spezifischen Adapter verwenden.

Vanilla TypeScript
Vue
Nuxt
React
Next.js
Svelte

Lokal entwickelt

Der Optimizer lädt deine Bilder nicht hoch

Die Bildverarbeitung findet lokal im Browser statt, bis die umgebende Anwendung entscheidet, was mit dem zurückgegebenen File geschehen soll.

jamit-image-optimizer sendet keine Bilder, Dateinamen, Optimierungsmetadaten oder Verarbeitungstelemetrie an einen JamIT-Dienst. Die eigene Upload- oder Analytics-Infrastruktur der Anwendung bleibt davon getrennt.

File API
Web Workers
WebAssembly
JPEG / PNG / WebP
Native HEIC / HEIF where available

Paketstatus

Veröffentlicht und bereit zur Integration

Die erste öffentliche Version enthält Einzelbild-Optimierung, Mixed-File-Batch-Verarbeitung, JPEG-, PNG- und WebP-Codecs, Resize- und Qualitätssteuerung, Zielgrößen-Optimierung, native HEIC/HEIF-Dekodierung sofern verfügbar, kontrollierte Parallelverarbeitung, Abort-Unterstützung und detaillierte Ergebnis-Metadaten.

Das Paket ist auf npm veröffentlicht. Quellcode, Tests und der Entwicklungs-Playground sind öffentlich auf GitHub verfügbar.

Veröffentlicht

Open Source

Den Quellcode auf GitHub ansehen

Implementierung, Browser-Tests, Worker-Pipeline und öffentliche API können direkt im Repository eingesehen werden. Dort können auch Issues gemeldet werden.

GitHub-Repository öffnen