Frontend · Package reference

@wrnexus/image

Responsive image optimization, loaders, placeholders, and components.

v0.8.7Private registryFrontend

Install the package

After WorkRoot approves private registry access, install the release-aligned package:

bun add @wrnexus/image@0.8.7

Request preview access. Never put registry tokens in source control.

Secure responsive-image planning, loader adapters, picture sources, preload hints, placeholders, and performance auditing for WRNexusJS.

Build-time conversion is available through optimizeImage. It normalizes and bounds width/format variants, prevents variant explosions, writes deterministic filenames, and returns a manifest with dimensions and byte sizes:

import { optimizeImage } from "@wrnexus/image";

const manifest = await optimizeImage("public/hero.jpg", {
  outputDir: "public/generated/images",
  widths: [480, 960, 1440],
  formats: ["avif", "webp"],
  quality: 80,
});

Install the optional sharp peer (bun add sharp) for the default AVIF/WebP processor. Build systems can instead supply an ImageProcessor adapter, which also makes transformation pipelines deterministic in tests.

Helper API

import {
  createResponsiveImage,
  createPicture,
  createCdnImageLoader,
  createPathImageLoader,
  createBlurPlaceholder,
  imagePreload,
  auditImage,
} from "@wrnexus/image";

const loader = createCdnImageLoader("https://images.example.com/transform");
const picture = createPicture({
  src: "/hero.jpg",
  alt: "Product dashboard",
  width: 1600,
  height: 900,
  widths: [480, 768, 1200, 1600],
  formats: ["avif", "webp"],
  sizes: "(max-width: 768px) 100vw, 1200px",
  fetchPriority: "high",
  loader,
});

Remote loaders require HTTPS. Source URLs are validated, dimensions and quality are bounded, placeholder colors are restricted to safe CSS colors, and preload attributes are escaped.

Components

Enable imagePlugin() and use:

<OptimizedImage />
<Picture />
<ImageCard />

The package-owned blocks compose @wrnexus/ui where a complete UI block is appropriate while keeping the low-level image element lightweight.

Complete TypeScript API

Generated from the exact installed package declarations.

export { ImagePluginOptions, imageComponentsDir, default as imagePlugin } from './plugin.js';
import '@wrnexus/plugin';

interface ImageProcessorResult {
    data: Uint8Array;
    width: number;
    height: number;
}
interface ImageProcessor {
    transform(input: string, options: {
        width: number;
        format: Exclude<ImageFormat, "original">;
        quality: number;
    }): Promise<ImageProcessorResult>;
}
interface OptimizeImageOptions {
    outputDir: string;
    widths: number[];
    formats?: Array<Exclude<ImageFormat, "original">>;
    quality?: number;
    maxVariants?: number;
    processor?: ImageProcessor;
}
interface OptimizedImageVariant {
    path: string;
    width: number;
    height: number;
    format: Exclude<ImageFormat, "original">;
    bytes: number;
}
interface OptimizedImageManifest {
    source: string;
    variants: OptimizedImageVariant[];
}
declare function optimizeImage(input: string, options: OptimizeImageOptions): Promise<OptimizedImageManifest>;

type ImageFormat = "avif" | "webp" | "jpeg" | "png" | "original";
interface ImageLoaderInput {
    src: string;
    width: number;
    quality?: number;
    format?: ImageFormat;
}
type ImageLoader = (input: ImageLoaderInput) => string;
interface ImagePolicy {
    remoteHosts?: string[];
    allowedProtocols?: string[];
    maxWidth?: number;
    maxQuality?: number;
}
interface ResponsiveImageOptions extends ImagePolicy {
    src: string;
    alt: string;
    width: number;
    height: number;
    widths?: number[];
    sizes?: string;
    quality?: number;
    format?: ImageFormat;
    loading?: "eager" | "lazy";
    fetchPriority?: "high" | "low" | "auto";
    decoding?: "async" | "sync" | "auto";
    loader?: ImageLoader;
    class?: string;
}
interface ResponsiveImageAttributes {
    src: string;
    srcset?: string;
    sizes?: string;
    alt: string;
    width: string;
    height: string;
    loading: "eager" | "lazy";
    decoding: "async" | "sync" | "auto";
    fetchpriority?: "high" | "low" | "auto";
    class?: string;
}
interface ImageAuditInput {
    src: string;
    width?: number;
    height?: number;
    renderedWidth?: number;
    bytes?: number;
    loading?: string;
    fetchPriority?: string;
    isLcp?: boolean;
}
interface ImageAuditIssue {
    code: string;
    severity: "error" | "warning" | "info";
    message: string;
}
declare const defaultImageLoader: ImageLoader;
declare function createResponsiveImage(options: ResponsiveImageOptions): ResponsiveImageAttributes;
declare function auditImage(input: ImageAuditInput): ImageAuditIssue[];
interface PictureSource {
    type: string;
    srcset: string;
    sizes?: string;
}
interface PicturePlan {
    image: ResponsiveImageAttributes;
    sources: PictureSource[];
}
declare function normalizeImageWidths(widths: readonly number[], options?: {
    min?: number;
    max?: number;
}): number[];
declare function createCdnImageLoader(baseUrl: string, options?: {
    sourceParam?: string;
    widthParam?: string;
    qualityParam?: string;
    formatParam?: string;
}): ImageLoader;
declare function createPathImageLoader(prefix?: string): ImageLoader;
declare function createPicture(options: ResponsiveImageOptions & {
    formats?: ImageFormat[];
}): PicturePlan;
declare function createBlurPlaceholder(options?: {
    width?: number;
    height?: number;
    color?: string;
    accent?: string;
}): string;
declare function imagePreload(image: ResponsiveImageAttributes, options?: {
    as?: string;
    type?: string;
    crossOrigin?: "anonymous" | "use-credentials";
}): string;
declare function imageCacheKey(input: ImageLoaderInput): string;

export { type ImageAuditInput, type ImageAuditIssue, type ImageFormat, type ImageLoader, type ImageLoaderInput, type ImagePolicy, type ImageProcessor, type ImageProcessorResult, type OptimizeImageOptions, type OptimizedImageManifest, type OptimizedImageVariant, type PicturePlan, type PictureSource, type ResponsiveImageAttributes, type ResponsiveImageOptions, auditImage, createBlurPlaceholder, createCdnImageLoader, createPathImageLoader, createPicture, createResponsiveImage, defaultImageLoader, imageCacheKey, imagePreload, normalizeImageWidths, optimizeImage };

Examples

Copy-ready examples from the installed package documentation.

filenames, and returns a manifest with dimensions and byte sizes

import { optimizeImage } from "@wrnexus/image";

const manifest = await optimizeImage("public/hero.jpg", {
  outputDir: "public/generated/images",
  widths: [480, 960, 1440],
  formats: ["avif", "webp"],
  quality: 80,
});

## Helper API

import {
  createResponsiveImage,
  createPicture,
  createCdnImageLoader,
  createPathImageLoader,
  createBlurPlaceholder,
  imagePreload,
  auditImage,
} from "@wrnexus/image";

const loader = createCdnImageLoader("https://images.example.com/transform");
const picture = createPicture({
  src: "/hero.jpg",
  alt: "Product dashboard",
  width: 1600,
  height: 900,
  widths: [480, 768, 1200, 1600],
  formats: ["avif", "webp"],
  sizes: "(max-width: 768px) 100vw, 1200px",
  fetchPriority: "high",
  loader,
});