@nocojs/core

Core logic that drives image placeholder and optimization workflows across the nocojs ecosystem. It provides the AST transformer, placeholder generator, responsive image builder, and a lightweight SQLite cache used by every bundler integration.

Overview

• TypeScript implementation – built with sharp, oxc-parser, and Node.js primitives
• Server utilities – programmatic helpers for generating placeholders or full responsive image sets.
• Bundler transforms – AST walker that replaces placeholder() calls at build time when used with an integration like @nocojs/rollup-plugin or @nocojs/webpack-loader.
• SQLite caching – deduplicates work across builds while keeping placeholder metadata available to transformers.

The nocojs package re-exports everything you need:

• Client: placeholder() – converted to inline data URIs by the bundler.
• Server / build scripts: getPlaceholder() and the new getOptimizedImage() helper.

You should not need to import anything directly from @nocojs/core in application code.

Quick Start

Client-side components

import { placeholder } from "nocojs";

export function HeroImage() {
	return <img src={placeholder("/images/hero.jpg")} alt="Hero" />;
}

With a supported bundler plugin/loader the call above is replaced with the generated placeholder string during the build.

Server-side rendering or build scripts

import { getPlaceholder, getOptimizedImage } from "nocojs";

const thumbnail = await getPlaceholder("./public/blog/cover.jpg", {
	placeholderType: "blurred",
	width: 16,
});

const responsive = await getOptimizedImage("./public/blog/cover.jpg", {
	outputDir: "./public/generated",
	widths: [640, 960, 1280],
	formats: ["webp", "jpg"],
	baseUrl: "/generated",
});

console.log(thumbnail.placeholder); // data:image/svg+xml;base64,...
console.log(responsive.srcset);     // ["/generated/cover-640w.webp 640w", ...]

API Reference

getPlaceholder(url, options?)

Generates a lightweight placeholder for a local file path or remote URL. Results include the base64 data URI and the original dimensions so you can preserve aspect ratio.

import { getPlaceholder } from "nocojs";

const result = await getPlaceholder("/images/team.jpg", {
	placeholderType: "dominant-color",
	cacheFileDir: ".nocojs",
	wrapWithSvg: true,
});

// result: GetPlaceholderImageResult
// {
//   placeholder: string;
//   originalWidth: number;
//   originalHeight: number;
//   placeholderPng?: string;
// }

GetPlaceholderOptions

interface GetPlaceholderOptions {
	placeholderType?: "normal" | "blurred" | "grayscale" | "dominant-color" | "average-color" | "transparent";
	width?: number;
	height?: number;
	wrapWithSvg?: boolean;
	cache?: boolean;
	cacheFileDir?: string;
	_enableLogging?: boolean; // diagnostic logging for cache hits
}

getOptimizedImage(url, options)

Creates responsive image variants, optional format conversions, and an accompanying placeholder in a single call.

import { getOptimizedImage } from "nocojs";

const result = await getOptimizedImage("./public/gallery/photo.jpg", {
	outputDir: "./public/generated/gallery",
	widths: [480, 768, 1024],
	formats: ["webp", "avif"],
	quality: 75,
	baseUrl: "/generated/gallery",
	namingPattern: "{name}-{width}w.{format}",
	placeholderOptions: {
		placeholderType: "blurred",
	},
});

// result: GetOptimizedImageOutput
// {
//   srcset: string[];        // one entry per format
//   images: SrcsetImage[];   // [{ width, height, src, filePath, format }, ...]
//   placeholder: string | null;
//   isError: boolean;
//   meta: { width: number; height: number; format: string };
// }

GetOptimizedImageOptions

interface GetOptimizedImageOptions {
	outputDir: string;               // required destination for generated files
	widths?: number[];               // defaults to [320, 640, 960, 1280, 1920]
	baseUrl?: string;                // appended to generated filenames in srcset entries
	formats?: string[];              // defaults to the source format when omitted
	quality?: number;                // passed to sharp encoders (default 80)
	namingPattern?: string;          // defaults to "{name}-{width}w.{format}"
	placeholderOptions?: GetPlaceholderOptions | null; // set to null to skip placeholder generation
	cache?: boolean;                 // skip rewriting existing files when true (default)
}

Bundler Transformation Flow

• Import placeholder from nocojs inside your UI code.
• The bundler integration (@nocojs/rollup-plugin, @nocojs/webpack-loader, @nocojs/rspack-loader, @nocojs/parcel-transformer) invokes the transformer from @nocojs/core.
• The transformer finds placeholder("/path") calls, generates placeholders with the configured options, and replaces the call with the inlined data URI.

Caching & Performance

• Placeholder metadata is cached in a SQLite database under .nocojs/cache.db by default.
• Store handles in-memory caching during a single transform run while the database enables cross-build reuse.
• Image processing pipelines are powered by sharp, and AST traversal uses oxc-parser for fast JavaScript/TypeScript parsing.

Development

npm install
npm run build --workspace @nocojs/core
npm run test --workspace @nocojs/core

You can also run rolldown -w -c inside packages/core for watch mode and vitest for the test suite. The project targets modern Node.js environments (18+) and relies purely on the TypeScript toolchain.

License

MIT – see the repository root for details.

Contributing

This package lives inside the nocojs monorepo. Refer to the top-level README for contribution guidelines and workspace development notes.