@lonik/oh-image 0.0.1 → 1.0.2

package/README.md

@@ -1,7 +1,30 @@
-# oh-image
+# react-components-starter
 
-This library was generated with [Nx](https://nx.dev).
+A starter for creating a React component library.
 
-## Running unit tests
+## Development
 
-Run `nx test oh-image` to execute the unit tests via [Vitest](https://vitest.dev/).
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run the playground:
+
+```bash
+npm run play
+```
+
+- Run the unit tests:
+
+```bash
+npm run test
+```
+
+- Build the library:
+
+```bash
+npm run build
+```
+# tsdown-template

package/dist/plugin.d.ts

@@ -0,0 +1,58 @@
+import { FormatEnum } from "sharp";
+import * as vite0 from "vite";
+import * as rollup0 from "rollup";
+
+//#region src/plugin/types.d.ts
+/**
+ * Configuration options for the oh-image Vite plugin.
+ * Extends ImageOptions with all properties required, plus plugin-specific settings.
+ */
+interface PluginConfig extends Required<ImageOptions> {
+  /** Directory name where processed images will be output during build */
+  distDir: string;
+}
+/**
+ * Options for image processing and transformation.
+ * Can be passed via query parameters or plugin configuration.
+ */
+interface ImageOptions {
+  /** Target width for the processed image in pixels */
+  width?: number | null;
+  /** Target height for the processed image in pixels */
+  height?: number | null;
+  /** Output format for the main image (e.g., 'webp', 'avif', 'png') */
+  format?: keyof FormatEnum | null;
+  /** Blur amount (true for default blur, or a number for sigma value) */
+  blur?: number | boolean;
+  /** Whether to generate a placeholder image for lazy loading */
+  placeholder?: boolean;
+  /** Width of the placeholder image in pixels */
+  placeholderW?: number;
+  /** Height of the placeholder image in pixels */
+  placeholderH?: number;
+  /** Output format for the placeholder image */
+  placeholderF?: keyof FormatEnum;
+  /** Blur setting for the placeholder (true for default, or sigma value) */
+  placeholderB: boolean | number;
+  /** Breakpoints array - widths in pixels for responsive srcSet generation */
+  bps?: number[];
+  /** Output format for srcSet images */
+  srcSetsF: keyof FormatEnum;
+}
+//#endregion
+//#region src/plugin/plugin.d.ts
+declare function ohImage(options?: Partial<PluginConfig>): {
+  name: string;
+  configResolved(this: vite0.MinimalPluginContextWithoutEnvironment, viteConfig: vite0.ResolvedConfig): void;
+  enforce: "pre";
+  configureServer(this: vite0.MinimalPluginContextWithoutEnvironment, server: vite0.ViteDevServer): void;
+  load: {
+    filter: {
+      id: RegExp;
+    };
+    handler(this: rollup0.PluginContext, id: string): Promise<string | null>;
+  };
+  writeBundle(this: rollup0.PluginContext): Promise<void>;
+};
+//#endregion
+export { ohImage };

package/dist/plugin.js

@@ -0,0 +1,221 @@
+import { basename, dirname, extname, join, parse } from "node:path";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import queryString from "query-string";
+import sharp from "sharp";
+import pLimit from "p-limit";
+
+//#region src/plugin/utils.ts
+function getRandomString(length = 32) {
+	return randomBytes(Math.ceil(length * 3 / 4)).toString("base64").slice(0, length).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+async function readFileSafe(path) {
+	try {
+		return await readFile(path);
+	} catch {
+		return null;
+	}
+}
+async function saveFileSafe(path, data) {
+	const dir = dirname(path);
+	try {
+		await mkdir(dir, { recursive: true });
+		await writeFile(path, data);
+		console.log(`Successfully saved to ${path}`);
+	} catch (err) {
+		console.error("Failed to save file:", err);
+	}
+}
+function queryToOptions(processKey, uri) {
+	const [path, query] = uri.split("?");
+	if (!query || !path) return {
+		shouldProcess: false,
+		path: ""
+	};
+	const parsed = queryString.parse(query, {
+		parseBooleans: true,
+		parseNumbers: true,
+		arrayFormat: "comma"
+	});
+	if (processKey in parsed) return {
+		shouldProcess: true,
+		options: parsed,
+		path
+	};
+	else return {
+		shouldProcess: false,
+		path
+	};
+}
+async function processImage(path, options) {
+	let processed = sharp(path);
+	if (options.width || options.height) processed = processed.resize({
+		width: options.width ?? void 0,
+		height: options.height ?? void 0
+	});
+	if (options.format) processed = processed.toFormat(options.format);
+	if (options.blur) processed = processed.blur(options.blur);
+	return await processed.toBuffer();
+}
+
+//#endregion
+//#region src/plugin/plugin.ts
+const DEFAULT_CONFIGS = {
+	distDir: "oh-images",
+	bps: [
+		16,
+		48,
+		96,
+		128,
+		384,
+		640,
+		750,
+		828,
+		1080,
+		1200,
+		1920
+	],
+	format: "webp",
+	blur: false,
+	width: null,
+	height: null,
+	placeholder: false,
+	placeholderH: 100,
+	placeholderW: 100,
+	placeholderB: true,
+	placeholderF: "webp",
+	srcSetsF: "webp"
+};
+const PROCESS_KEY = "oh";
+const SUPPORTED_IMAGE_FORMATS = /\.(jpe?g|png|webp|avif|gif|tiff?|svg)(\?.*)?$/i;
+const DEV_DIR = "/@oh-images/";
+function ohImage(options) {
+	let isBuild = false;
+	let assetsDir;
+	let outDir;
+	let cacheDir;
+	const imageEntries = /* @__PURE__ */ new Map();
+	const config = {
+		...DEFAULT_CONFIGS,
+		...options
+	};
+	/**
+	* used for dev server to match url to path
+	* @param url
+	*/
+	function urlToPath(url) {
+		const fileId = basename(url);
+		return join(cacheDir, fileId);
+	}
+	function genIdentifier(uri, format, prefix) {
+		const fileId = basename(uri);
+		const uniqueFileId = `${prefix}-${getRandomString()}-${fileId}.${format}`;
+		if (!isBuild) return join(DEV_DIR, uniqueFileId);
+		return join(assetsDir, config.distDir, uniqueFileId);
+	}
+	return {
+		name: "oh-image",
+		configResolved(viteConfig) {
+			cacheDir = join(viteConfig.cacheDir, DEV_DIR);
+			isBuild = viteConfig.command === "build";
+			assetsDir = viteConfig.build.assetsDir;
+			outDir = join(viteConfig.root, viteConfig.build.outDir);
+		},
+		enforce: "pre",
+		configureServer(server) {
+			server.middlewares.use(async (req, res, next) => {
+				const url = req.url;
+				if (!url?.includes(DEV_DIR) || !SUPPORTED_IMAGE_FORMATS.test(url)) return next();
+				const path = urlToPath(url);
+				const ext = extname(url).slice(1);
+				const image = await readFileSafe(path);
+				const imageEntry = imageEntries.get(url);
+				if (!imageEntry) {
+					console.warn("Image entry not found with id: " + url);
+					next();
+					return;
+				}
+				if (image) {
+					res.setHeader("Content-Type", `image/${ext}`);
+					res.end(image);
+					return;
+				}
+				const processed = await processImage(imageEntry.origin, imageEntry);
+				await saveFileSafe(path, processed);
+				res.setHeader("Content-Type", `image/${ext}`);
+				res.end(processed);
+			});
+		},
+		load: {
+			filter: { id: SUPPORTED_IMAGE_FORMATS },
+			async handler(id) {
+				try {
+					const parsed = queryToOptions(PROCESS_KEY, id);
+					if (!parsed.shouldProcess) return null;
+					const origin = parsed.path;
+					const { name, ext } = parse(parsed.path);
+					const metadata = await sharp(parsed.path).metadata();
+					const mergedOptions = {
+						...config,
+						...parsed.options
+					};
+					const mainIdentifier = genIdentifier(name, mergedOptions.format ?? ext.slice(1), "main");
+					const mainEntry = {
+						width: mergedOptions.width,
+						height: mergedOptions.height,
+						blur: mergedOptions.blur,
+						format: mergedOptions.format,
+						origin
+					};
+					imageEntries.set(mainIdentifier, mainEntry);
+					const src = {
+						width: metadata.width,
+						height: metadata.height,
+						src: mainIdentifier,
+						srcSets: []
+					};
+					if (parsed.options?.placeholder) {
+						const placeholderIdentifier = genIdentifier(name, mergedOptions.placeholderF, "placeholder");
+						const placeholderEntry = {
+							width: mergedOptions.placeholderW,
+							height: mergedOptions.placeholderH,
+							format: mergedOptions.placeholderF,
+							blur: mergedOptions.placeholderB,
+							origin
+						};
+						imageEntries.set(placeholderIdentifier, placeholderEntry);
+						src.placeholderUrl = placeholderIdentifier;
+					}
+					if (mergedOptions.bps) for (const breakpoint of mergedOptions.bps) {
+						const srcSetIdentifier = genIdentifier(name, mergedOptions.srcSetsF, `breakpoint-${breakpoint}`);
+						const srcSetEntry = {
+							width: breakpoint,
+							format: mergedOptions.srcSetsF,
+							origin
+						};
+						imageEntries.set(srcSetIdentifier, srcSetEntry);
+						src.srcSets.push({
+							src: srcSetIdentifier,
+							width: `${breakpoint}w`
+						});
+					}
+					return `export default ${JSON.stringify(src)};`;
+				} catch (err) {
+					console.error(`Couldn't load image with id: ${id} error:${err}`);
+					return null;
+				}
+			}
+		},
+		async writeBundle() {
+			const limit = pLimit(30);
+			const tasks = Array.from(imageEntries, ([key, value]) => limit(async () => {
+				const processed = await processImage(value.origin, value);
+				await saveFileSafe(join(outDir, key), processed);
+			}));
+			await Promise.all(tasks);
+		}
+	};
+}
+
+//#endregion
+export { ohImage };

package/dist/react.d.ts

@@ -0,0 +1,55 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { CSSProperties } from "react";
+
+//#region src/react/types.d.ts
+/**
+ * Image source type - can be either a simple URL string or a full ImageSrc object
+ */
+type ImageSrcType = string | ImageSrc;
+/**
+ * Optimized image source with multiple responsive variants
+ */
+interface ImageSrc {
+  /** Original image width in pixels */
+  width: number;
+  /** Original image height in pixels */
+  height: number;
+  /** Optional low-quality placeholder image URL for blur-up effect */
+  placeholderUrl?: string;
+  /** Array of responsive image variants for different screen sizes */
+  srcSets: ImageSrcSet[];
+  /** Primary image source URL */
+  src: string;
+}
+/**
+ * Single responsive image variant in a srcset
+ */
+interface ImageSrcSet {
+  /** Width descriptor (e.g., "1920w") */
+  width: string;
+  /** Image URL for this variant */
+  src: string;
+}
+/**
+ * Props for the optimized Image component
+ * Extends standard HTML image attributes with optimization features
+ */
+interface ImageProps extends Partial<Pick<HTMLImageElement, "alt" | "fetchPriority" | "decoding" | "loading" | "height" | "width" | "srcset" | "className" | "sizes">> {
+  /** Load the image immediately, bypassing lazy loading */
+  asap?: boolean;
+  /** Image source - either a URL string or ImageSrc object with responsive variants */
+  src: ImageSrcType;
+  /** Override placeholder URL (takes precedence over ImageSrc.placeholderUrl) */
+  placeholderUrl?: string | undefined;
+  /** Enable blur-up placeholder effect during image loading */
+  placeholder?: boolean;
+  /** Inline CSS styles */
+  style?: CSSProperties;
+  /** Make image fill its container (position: absolute) */
+  fill?: boolean;
+}
+//#endregion
+//#region src/react/image.d.ts
+declare function Image(props: ImageProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { Image, type ImageProps, type ImageSrc, type ImageSrcSet };

package/dist/react.js

@@ -0,0 +1,73 @@
+import { preload } from "react-dom";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react/image.tsx
+function resolveOptions(props) {
+	const { src, ...rest } = props;
+	const resolved = { ...rest };
+	if (typeof src === "object") {
+		resolved.src = src.src;
+		resolved.width ??= src.width;
+		resolved.height ??= src.height;
+		resolved.srcset ??= src.srcSets.map((set) => `${set.src} ${set.width}`).join(", ");
+		resolved.placeholderUrl ??= src.placeholderUrl;
+	} else resolved.src = src;
+	if (props.asap) {
+		resolved.decoding = "async";
+		resolved.loading = "eager";
+		resolved.fetchPriority = "high";
+		preload(resolved.src, {
+			as: "image",
+			fetchPriority: "high"
+		});
+	}
+	if (props.fill) resolved.sizes ||= "100vw";
+	return resolved;
+}
+function getPlaceholderStyles(props) {
+	if (!props.placeholder) return {};
+	if (!props.placeholderUrl) {
+		console.warn("Blur URL is required for placeholder");
+		return {};
+	}
+	return {
+		backgroundPosition: "50% 50%",
+		backgroundRepeat: "no-repeat",
+		backgroundImage: `url(${props.placeholderUrl})`,
+		backgroundSize: "cover"
+	};
+}
+function getFillStyles(props) {
+	if (!props.fill) return {};
+	return {
+		width: "100%",
+		height: "100%",
+		inset: "0"
+	};
+}
+function Image(props) {
+	const options = resolveOptions(props);
+	const placeholderStyles = getPlaceholderStyles(options);
+	const fillStyles = getFillStyles(options);
+	const styles = {
+		...placeholderStyles,
+		...fillStyles,
+		...props.style
+	};
+	return /* @__PURE__ */ jsx("img", {
+		className: props.className,
+		style: styles,
+		src: options.src,
+		width: options.width,
+		height: options.height,
+		srcSet: options.srcset,
+		alt: options.alt,
+		loading: options.loading,
+		decoding: options.decoding,
+		sizes: options.sizes,
+		fetchPriority: options.fetchPriority ?? "auto"
+	});
+}
+
+//#endregion
+export { Image };

package/package.json

@@ -1,37 +1,74 @@
 {
   "name": "@lonik/oh-image",
-  "version": "0.0.1",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
+  "version": "1.0.2",
+  "description": "A React component library for optimized image handling.",
+  "author": "Luka Onikadze <lukonik@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/lukonik/oh-image#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lukonik/oh-image.git",
-    "directory": "packages/oh-image"
+    "url": "git+https://github.com/lukonik/oh-image.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lukonik/oh-image/issues"
   },
-  "keywords": [
-    "image",
-    "optimization",
-    "processing"
-  ],
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
-    ".": {
-      "@oh-image/source": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
     }
   },
   "files": [
-    "dist",
-    "!**/*.tsbuildinfo"
+    "dist"
   ],
-  "nx": {
-    "name": "oh-image"
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "play": "vite",
+    "play:build": "vite build",
+    "play:preview": "vite preview",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp && pnpm publish",
+    "prepublishOnly": "pnpm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/browser-playwright": "^4.0.16",
+    "bumpp": "^10.3.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "globals": "^17.3.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "vitest-browser-react": "^2.0.2",
+    "@commitlint/config-conventional": "^20.4.1"
+  },
+  "dependencies": {
+    "p-limit": "^7.3.0",
+    "query-string": "^9.3.1"
   }
-}
+}