blur64

Generate tiny, base64-encoded blurred image placeholders from images — a file path, a URL, or a Buffer — using Sharp. The result is a small data URL you can inline as an image placeholder (for example as a Next.js blurDataURL) while the full image loads.

Features

• Flexible input — file path, URL, or Buffer
• Tiny output — downscale, re-encode, and blur yields very small data URLs
• Configurable — size/scale, blur strength, format (avif, webp, jpeg, png), quality, color adjustments, and more
• Next.js helpers — server actions with ISR support, tailored for the App Router, via blur64/nextjs
• Network resilience — automatic retries with exponential backoff for URL fetches

Requirements

• Node.js >= 20 (CI runs 20, 22, and 24)
• sharp ^0.33.5, ^0.34.2, or ^0.35.0 (a peer dependency — install it alongside blur64)

Installation

npm install blur64 sharp

Usage

Quick start

import { blur64Image } from "blur64";

const { width, height, blurDataURL } = await blur64Image(
  "https://example.com/image.jpg"
);

console.log(blurDataURL); // data:image/avif;base64,...
console.log(width, height); // original image dimensions

With no options, blur64Image downscales the image so its smaller side is 24px, re-encodes it as AVIF at quality 20, and applies a light blur — the defaults that give blur64 placeholders their smooth look (see Options).

File path and Buffer inputs

// From a local file
const fromFile = await blur64Image("./photo.jpg");

// From a Buffer
import { readFile } from "node:fs/promises";
const buffer = await readFile("./photo.jpg");
const fromBuffer = await blur64Image(buffer);

With options

const result = await blur64Image({
  src: "https://example.com/image.jpg",
  size: 32,
  blurRadius: 8,
  format: "webp",
  quality: 30,
});

Error handling

Invalid options throw a Blur64Error. A URL that cannot be fetched (after retries) does not throw — it resolves to { width: 0, height: 0, blurDataURL: undefined } instead.

import { blur64Image, Blur64Error } from "blur64";

try {
  const result = await blur64Image("invalid/path.jpg");
  console.log(result);
} catch (error) {
  if (error instanceof Blur64Error) console.error(error.message);
  else console.error("Unexpected error:", error);
}

Next.js (App Router)

Compatibility: built for the App Router and React Server Components, and verified end-to-end on Next.js 16.4 with React 19.3 — Turbopack production build, static prerendering, route handlers, and the next/image blur placeholder all exercised against the published package. The helpers run entirely on the server and need no client-side JavaScript.

Import the helpers from blur64/nextjs:

// app/page.tsx
import Image from "next/image";
import { blur64NextImageData } from "blur64/nextjs";

export default async function Page() {
  const placeholder = await blur64NextImageData("https://example.com/image.jpg");
  return <Image src="https://example.com/image.jpg" alt="Demo" {...placeholder} />;
}

• blur64NextImageData(input, options?) returns Blur64ImageData plus a placeholder field — "blur" when a valid blurDataURL was produced, "empty" otherwise — ready to spread onto Next.js's Image component.
• blur64Action(input, options?) is a plain server action that returns Blur64ImageData and resolves to empty data instead of throwing on error.
• The Next.js variant accepts one extra option, revalidate (ISR cache lifetime for URL fetches; see below).

API

blur64Image(input, options?)

blur64Image(
  input: string | Buffer | Blur64Options,
  options?: Omit<Blur64Options, "src">
): Promise<Blur64ImageData>

Pass the source and options either as a single object or positionally.

Options (Blur64Options)

Option	Type	Default	Description
src	string | Buffer	—	Image source (file path, URL, or buffer).
scale	number (0 < scale ≤ 1)	—	Scale factor relative to the original dimensions.
size	number | { width: number; height: number }	24	Target size of the placeholder; the smaller side when a number.
ratio	number | { width: number; height: number }	original	Target aspect ratio.
blurRadius	number (> 0) | false | BlurOptions	4	Blur strength; false disables blurring.
quality	number (0–100)	20	Quality for lossy formats.
format	"avif" | "webp" | "jpeg" | "png"	"avif"	Output format.
formatOptions	object	—	Extra options for the selected format (see the Sharp docs).
brightness	number	1	Brightness multiplier.
saturation	number	1.2	Saturation multiplier.
hue	number	0	Hue rotation in degrees.
lightness	number	0	Lightness adjustment.
fit	"contain" | "cover" | "fill" | "inside" | "outside"	"inside"	Resize fit mode.
kernel	"nearest" | "cubic" | "mitchell" | "lanczos2" | "lanczos3"	"lanczos3"	Resize kernel.
retries	number	2	Retry attempts for URL fetches.
retryDelay	number (ms)	300	Base delay between retries (doubles each attempt).
timeout	number (ms)	30000	Request timeout for URL fetches.

Next.js options (Blur64NextOptions)

Extends Blur64Options with:

Option	Type	Default	Description
revalidate	number | false	86400	ISR revalidation time in seconds (24 hours); false disables caching.

Returns (Blur64ImageData)

Field	Type	Description
width	number	Original image width.
height	number	Original image height.
blurDataURL	string | undefined	Base64 data URL, or undefined on failure.

Notes

• Server-side only — blur64 uses sharp and runs in Node.js and Next.js server runtimes, not in the browser.
• URL fetches are retried with exponential backoff (retries, retryDelay, timeout); a fetch that still fails resolves to empty data rather than throwing.

Compatibility

blur64 is built to be safe to depend on:

• Stable API. The public surface — blur64Image, blur64Action, blur64NextImageData, Blur64Error, supportedFormats, the option and result types, and both entry points (blur64, blur64/nextjs) — does not change in minor or patch releases. An explicit compatibility test suite pins it, so an accidental breaking change fails CI.
• Wide sharp support. The peer range covers sharp 0.33, 0.34, and 0.35, each verified against this code. Your app keeps the sharp version it already has; blur64 does not force an upgrade.
• Stable output per sharp version. The placeholder bytes come from sharp's encoder, so they can differ between sharp versions — but for a given sharp version the output is pinned byte-for-byte by golden tests and does not drift between blur64 releases. (On sharp 0.34.5, blur64 1.4.0 reproduces the original v1.3.0 outputs exactly.)
• Both module systems. Every entry point ships ESM and CommonJS builds with types, so import and require consumers are equally supported.
• Next.js / React. The blur64/nextjs helpers target the App Router (Next.js 13.4+) and React Server Components (React 18+); verified end-to-end on Next.js 16.4 / React 19.3.

Development

npm install
npm run typecheck  # tsc --noEmit
npm test           # vitest, including golden-output tests
npm run build      # bundle CJS + ESM + types to dist/ with tsup

The test suite includes golden-output tests: the exact output of the default settings (and a matrix of options) is pinned byte-for-byte, so changes cannot silently alter the placeholders the package generates.

Releasing

Releases are published to npm by the Publish to npm GitHub Action: create a GitHub Release for the new version tag (or run the workflow manually), and the workflow typechecks, tests, builds, and publishes with provenance. It expects an NPM_TOKEN repository secret.

License

MIT © devbux