Smartu

Intelligent image compression inspired by Zhitu, rebuilt for open-source browser, Node.js, CLI, website, and build-pipeline workflows.

Smartu focuses on the decision layer around compression: how an image is classified, when format conversion is worth trying, which quality level to use, and when to preserve the source because the result is not better.

npx smartu@latest ./ornpx skills add https://github.com/yeliex/smartu -g

Try online Developer doc

View source on GitHub

Actual image format detection instead of extension-only handling.

Shared strategy model for browser, Node.js, and CLI workflows.

Candidate comparison keeps the source when compression is not smaller.

Try compress in browser

PNG and JPEG compression with explicit WebP and AVIF candidates.

Preparing browser runtime

Compression strategy

Smartu inspects each image, selects a compression path, evaluates conversion candidates, and keeps the source when the compressed result is not smaller.

Detection

Reads the real image format before choosing a compression branch.

PNG

Uses alpha, palette, area, color count, and source size thresholds.

JPEG

Estimates source quality before selecting recompression quality.

Candidates

Tries PNG/JPEG conversion plus explicit WebP or AVIF outputs only when smaller.

Replacement

Keeps original-file replacement explicit and size-gated.

Runtime split

Node uses Sharp; browser compression stays on shared strategy and web codecs.

CLI for local batches

Compress files or directories into an output folder, try conversion candidates, or replace originals only after Smartu proves the primary output is smaller.

npx smartu ./images  --out ./compressed
npx smartu ./images  --format auto,webp,avif  --recursive
npx smartu ./images  --replace
npx smartu ./images  --json

Argument / option	Description
`<inputs...>`	input files or directories
`-o, --out <dir>`	write output files to a directory
`--replace`	replace the original path only when the primary output is smaller
`--recursive`	recurse into input directories
`--format <formats>`	comma-separated output formats: auto,png,jpg,jpeg,webp,avif; default keeps source format. auto tries PNG/JPEG conversion only, WebP/AVIF require explicit formats
`-q, --quality <quality>`	quality mode: auto, q1..q6, or a numeric adjustment
`--json`	print machine-readable results
`-h, --help`	display help for command

Use the same API from npm

Install one package and import from the root entrypoint. Conditional exports select the Sharp-based Node runtime or the WASM codec browser runtime.

Installation

npm install smartu

Browser

import { compressImage } from "smartu";

const result = await compressImage(file, {
  allowFormatConversion: true,
  generateWebp: true,
  generateAvif: true,
});

const url = URL.createObjectURL(result.primaryBlob);

Node.js

import { readFile, writeFile } from "node:fs/promises";
import { compressImage } from "smartu";

const input = await readFile("input.png");
const result = await compressImage(input);

await writeFile("output.png", result.primary.buffer);

API reference

Browser and Node resolve different runtime adapters, but keep the same main API names.

compressImage(input, options?)

Compresses an image and returns metadata, the chosen strategy plan, the primary output, and any smaller alternatives. Browser results also include Blob handles for object URLs.

analyzeImage(input)

Reads the actual encoded format, dimensions, source size, color count, alpha signal, PNG8 signal, and JPEG quality estimate.

createCompressionPlan(metadata, options?)

Builds the strategy plan without encoding outputs, which is useful when callers need to inspect routing decisions before running codecs.

CompressionOptions

Options tune candidate generation and quality offsets; runtimes still compare encoded sizes.

formats

Optional candidate list using auto, png, jpg, webp, or avif. When omitted, Smartu uses auto and keeps the source format as the primary path.

allowFormatConversion

Controls PNG/JPEG conversion candidates in auto mode. It defaults to true, while encoded outputs are still kept only when smaller.

generateWebp

Adds a WebP candidate beside the primary strategy output. WebP is opt-in instead of implied by auto.

generateAvif

Adds an AVIF candidate beside the primary strategy output. AVIF is opt-in instead of implied by auto.

qualityPreset

Accepts q1 through q6 as strategy offsets. q5 is neutral; other presets make branch-selected quality more or less aggressive.

qualityAdjustment

A numeric quality offset for callers that need direct tuning. When provided, it takes precedence over qualityPreset.