@assetopt/core

@assetopt/core

Pure asset optimization functions for images (sharp), CSS (lightningcss), JS (esbuild), and SVG (svgo). The engine behind the @assetopt/cli command-line tool, exported as a standalone library for programmatic use.

Open source, MIT.

Install

npm install @assetopt/core

Quick start

import { optimizeImage, optimizeCss, optimizeJs, optimizeSvg } from '@assetopt/core';
import { readFile } from 'node:fs/promises';

const buf = await readFile('photo.jpg');
const result = await optimizeImage(buf, { quality: { jpeg: 80 } });

console.log(result.format); // 'jpeg'
console.log(result.originalSize); // 824133
console.log(result.outputSize); // 245912
console.log(result.buffer); // Buffer with optimized bytes

Every optimizer is a pure function: a buffer in, an optimized buffer out. No hidden I/O, no global state.

API

Optimizers

Function	Underlying lib	Returns
optimizeImage(buffer, options?)	sharp	Promise<ImageBufferResult>
optimizeCss(buffer, options?)	lightningcss	CssBufferResult
optimizeJs(buffer, options?)	esbuild	Promise<JsBufferResult>
optimizeSvg(buffer, options?)	svgo	SvgBufferResult

All option types are optional with sensible defaults:

• ImageOptimizeOptions — { outputFormat?, formatMatrix?, quality?, stripMetadata?, skip? }
• CssOptimizeOptions — { minify? }
• JsOptimizeOptions — { minify? }
• SvgOptimizeOptions — { multipass?, minifyIds? }

Pipeline

For folder-level orchestration:

import { runPipeline, buildReport, loadConfig } from '@assetopt/core';

const { config } = await loadConfig(); // walk-up .assetoptrc
const assets = await runPipeline('./public', config);
const report = buildReport(assets, /* durationMs */ 0);

Format matrix with smart routing

formatMatrix accepts function values for content-aware routing:

import { optimizeImage } from '@assetopt/core';

await optimizeImage(buf, {
  formatMatrix: {
    // AVIF for transparent PNGs, WebP for opaque ones
    png: (ctx) => (ctx.hasAlpha ? 'avif' : 'webp'),
    jpeg: 'webp',
    webp: 'keep',
    avif: 'keep',
  },
});

This is exactly how the built-in web-perf preset works.

Exports

// Optimizers (pure functions)
export { optimizeImage, optimizeCss, optimizeJs, optimizeSvg };

// Pipeline / orchestration
export { dispatch, runPipeline, buildReport };

// Config
export { loadConfig, mergeConfig, resolveConfig, DEFAULTS, PRESETS };
export type { LoadedConfig };

// Utilities
export { scanDirectory, getAssetType, getFileSize };
export { CACHE_FILE }; // name of the on-disk cache manifest, relative to output.dir

// Types
export type {
  AssetType,
  AssetResult,
  OptimizeResult,
  ImageQualityOptions,
  ImageOptimizeOptions,
  ImageBufferResult,
  ImageSourceFormat,
  ImageMatrixTarget,
  FormatMatrixValue,
  FormatMatrixResolver,
  FormatRoutingContext,
  PresetName,
  CssOptimizeOptions,
  CssBufferResult,
  JsOptimizeOptions,
  JsBufferResult,
  SvgOptimizeOptions,
  SvgBufferResult,
  DispatchResult,
  AssetoptConfig,
};

Documentation

• Configuration reference — every option, every default, programmatic API for formatMatrix functions
• Feature catalog — behavior of each optimizer in plain English
• Project README

For the command-line interface, see @assetopt/cli.

License

MIT.