better-asset 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sazzadur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# better-asset
+
+[![npm version](https://img.shields.io/npm/v/better-asset)](https://www.npmjs.com/package/better-asset)
+[![license](https://img.shields.io/npm/l/better-asset)](./LICENSE)
+
+Config-driven image asset generator. Resize, convert, and generate favicons from a single JSON config.
+
+> Zero config UI. Just a JSON file and one command.
+
+## Install
+
+```bash
+npm install -g better-asset
+```
+
+Or use without installing:
+
+```bash
+npx better-asset
+```
+
+## Quick Start
+
+```bash
+# Create a starter config
+better-asset init
+
+# Edit assets.config.json, then generate
+better-asset
+```
+
+## CLI
+
+```
+better-asset                  Generate assets from config
+better-asset init             Create a starter config file
+better-asset --config <path>  Use a custom config file
+better-asset --help           Show help
+better-asset --version        Show version
+```
+
+## Supported Formats
+
+**Input:** svg, png, jpg/jpeg, webp, avif
+
+**Output:** png (default), webp, jpeg, avif, ico
+
+## Config File
+
+By default `better-asset` looks for `assets.config.json` in the current directory.
+
+Add a `$schema` key for editor autocompletion:
+
+```json
+{
+	"$schema": "https://unpkg.com/better-asset/assets.config.schema.json"
+}
+```
+
+### Example
+
+```json
+{
+	"$schema": "https://unpkg.com/better-asset/assets.config.schema.json",
+	"source_dir": "public/assets",
+
+	"assets": [
+		{
+			"name": "icon",
+			"source": "icon.svg",
+			"sizes": [48, 96, 144, 512],
+			"destination": "public/icons"
+		},
+		{
+			"name": "favicon",
+			"source": "favicon.svg",
+			"sizes": [16, 32, 48],
+			"destination": "public/icons",
+			"ico": {
+				"required": true,
+				"size": 96
+			}
+		},
+		{
+			"name": "opengraph-image",
+			"source": "icon.svg",
+			"sizes": ["1200x630"],
+			"destination": "public/icons",
+			"format": "jpeg"
+		}
+	]
+}
+```
+
+### Asset Fields
+
+| Field         | Type    | Required | Default | Description                                  |
+| ------------- | ------- | -------- | ------- | -------------------------------------------- |
+| `name`        | string  | yes      | —       | Base name for generated files                |
+| `source`      | string  | yes      | —       | Source filename (relative to `source_dir`)   |
+| `sizes`       | array   | yes      | —       | Sizes to generate                            |
+| `destination` | string  | yes      | —       | Output directory (relative to project root)  |
+| `format`      | string  | no       | `"png"` | Output format: `png`, `webp`, `jpeg`, `avif` |
+| `sizeInName`  | boolean | no       | auto    | Force include/exclude size in filename       |
+| `ico`         | object  | no       | —       | Generate a `favicon.ico`                     |
+
+## Size Rules
+
+**Square** — use a number:
+
+```
+48  →  48×48
+```
+
+**Rectangular** — use a string:
+
+```
+"1200x630"  →  1200×630
+```
+
+## sizeInName
+
+By default:
+
+- **Multiple sizes** → size is included (`icon-48.png`, `icon-96.png`)
+- **Single size** → size is omitted (`apple-touch-icon.png`)
+
+Override per asset:
+
+```json
+{ "sizeInName": true }
+{ "sizeInName": false }
+```
+
+## ICO Generation
+
+Add an `ico` object to generate a real `favicon.ico`:
+
+```json
+{
+	"ico": {
+		"required": true,
+		"size": 96
+	}
+}
+```
+
+| Field      | Type    | Default | Description                            |
+| ---------- | ------- | ------- | -------------------------------------- |
+| `required` | boolean | —       | Whether to generate the `.ico` file    |
+| `size`     | number  | `64`    | Size of the embedded PNG in the `.ico` |
+
+## License
+
+MIT

package/assets.config.schema.json

@@ -0,0 +1,85 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "better-asset Config",
+	"description": "Configuration for better-asset — a config-driven image asset generator.",
+	"type": "object",
+	"required": ["source_dir", "assets"],
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "Path to the JSON schema file (for editor support)."
+		},
+		"source_dir": {
+			"type": "string",
+			"description": "Directory containing source images, relative to the project root."
+		},
+		"assets": {
+			"type": "array",
+			"description": "List of asset definitions to generate.",
+			"items": {
+				"type": "object",
+				"required": ["name", "source", "sizes", "destination"],
+				"properties": {
+					"name": {
+						"type": "string",
+						"description": "Base name for generated files."
+					},
+					"source": {
+						"type": "string",
+						"description": "Source image filename (relative to source_dir). Supports: svg, png, jpg, jpeg, webp, avif."
+					},
+					"sizes": {
+						"type": "array",
+						"description": "Sizes to generate. Use a number for square (e.g. 48 → 48x48) or a string for rectangular (e.g. \"1200x630\").",
+						"items": {
+							"oneOf": [
+								{
+									"type": "integer",
+									"minimum": 1,
+									"description": "Square size in pixels."
+								},
+								{
+									"type": "string",
+									"pattern": "^\\d+x\\d+$",
+									"description": "Rectangular size as \"WIDTHxHEIGHT\"."
+								}
+							]
+						},
+						"minItems": 1
+					},
+					"destination": {
+						"type": "string",
+						"description": "Output directory for generated files, relative to the project root."
+					},
+					"format": {
+						"type": "string",
+						"enum": ["png", "webp", "jpeg", "jpg", "avif"],
+						"default": "png",
+						"description": "Output image format (default: png)."
+					},
+					"sizeInName": {
+						"type": "boolean",
+						"description": "Force include/exclude size in filename. Default: included when multiple sizes, omitted for single size."
+					},
+					"ico": {
+						"type": "object",
+						"description": "Generate a favicon.ico file from this asset.",
+						"required": ["required"],
+						"properties": {
+							"required": {
+								"type": "boolean",
+								"description": "Whether to generate the .ico file."
+							},
+							"size": {
+								"type": "integer",
+								"minimum": 1,
+								"default": 64,
+								"description": "Size of the embedded PNG in the .ico file (default: 64)."
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/bin/better-asset.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import path from "path";
+import fs from "fs/promises";
+import { generate } from "../src/generate.js";
+import { defaultConfig } from "../src/config.js";
+import * as log from "../src/log.js";
+
+const HELP = `
+  \x1b[1m\x1b[35mbetter-asset\x1b[0m — config-driven image asset generator
+
+  \x1b[1mUsage\x1b[0m
+
+    $ better-asset                  Generate assets from config
+    $ better-asset init             Create a starter config file
+    $ better-asset --config <path>  Use a custom config file
+    $ better-asset --help           Show this help
+    $ better-asset --version        Show version
+
+  \x1b[1mExamples\x1b[0m
+
+    $ better-asset
+    $ better-asset --config my-config.json
+    $ better-asset init
+
+  \x1b[1mLearn More\x1b[0m
+    For configuration and usage details, see the documentation:
+    https://npmjs.com/package/better-asset
+`;
+
+async function getVersion() {
+	const pkgPath = new URL("../package.json", import.meta.url);
+	const raw = await fs.readFile(pkgPath, "utf-8");
+	return JSON.parse(raw).version;
+}
+
+async function initConfig(cwd) {
+	const configPath = path.join(cwd, "assets.config.json");
+
+	try {
+		await fs.access(configPath);
+		log.warn(`assets.config.json already exists — skipping.`);
+		return;
+	} catch {
+		// doesn't exist, good
+	}
+
+	await fs.writeFile(configPath, JSON.stringify(defaultConfig(), null, "\t") + "\n");
+	log.banner();
+	log.success("assets.config.json", "created");
+	console.log();
+	log.info("Edit the config, then run \x1b[1mbetter-asset\x1b[0m to generate.");
+	console.log();
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP);
+		return;
+	}
+
+	if (args.includes("--version") || args.includes("-v")) {
+		console.log(await getVersion());
+		return;
+	}
+
+	const cwd = process.cwd();
+
+	if (args[0] === "init") {
+		await initConfig(cwd);
+		return;
+	}
+
+	const configFlagIndex = args.indexOf("--config");
+	const configFlag = configFlagIndex !== -1 ? args[configFlagIndex + 1] : undefined;
+
+	await generate(cwd, configFlag);
+}
+
+main().catch(err => {
+	log.error(err.message || err);
+	process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "better-asset",
+	"version": "0.1.0",
+	"description": "Config-driven image asset generator. Resize, convert, and generate favicons from a single JSON config.",
+	"type": "module",
+	"bin": {
+		"better-asset": "bin/better-asset.js"
+	},
+	"files": [
+		"bin",
+		"src",
+		"assets.config.schema.json",
+		"LICENSE"
+	],
+	"keywords": [
+		"image",
+		"asset",
+		"generator",
+		"favicon",
+		"ico",
+		"icon",
+		"sharp",
+		"resize",
+		"convert",
+		"webp",
+		"avif",
+		"png",
+		"cli"
+	],
+	"author": "Sazzadur Rahman",
+	"license": "MIT",
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"sharp": "^0.34.5"
+	}
+}

package/src/clean.js

@@ -0,0 +1,18 @@
+import fs from "fs/promises";
+import path from "path";
+import { fileExists } from "./fs-utils.js";
+
+export async function cleanGeneratedFiles(destinationDir, assetName) {
+	if (!(await fileExists(destinationDir))) return;
+
+	const files = await fs.readdir(destinationDir);
+
+	const patterns = [
+		new RegExp(`^${assetName}(-.*)?\\.(png|webp|jpeg|jpg|avif)$`),
+		...(assetName === "favicon" ? [/^favicon\.ico$/] : []),
+	];
+
+	await Promise.all(
+		files.filter(file => patterns.some(regex => regex.test(file))).map(file => fs.unlink(path.join(destinationDir, file))),
+	);
+}

package/src/config.js

@@ -0,0 +1,91 @@
+import path from "path";
+import fs from "fs/promises";
+
+const DEFAULT_CONFIG_NAME = "assets.config.json";
+
+/**
+ * Resolve the config file path.
+ * Priority: explicit path → default file in cwd.
+ */
+export function resolveConfigPath(cwd, configFlag) {
+	if (configFlag) {
+		return path.isAbsolute(configFlag) ? configFlag : path.join(cwd, configFlag);
+	}
+	return path.join(cwd, DEFAULT_CONFIG_NAME);
+}
+
+/**
+ * Load and validate the external JSON config.
+ */
+export async function loadConfig(configPath) {
+	try {
+		await fs.access(configPath);
+	} catch {
+		throw new Error(`Config file not found: ${configPath}\nRun \`better-asset init\` to create one.`);
+	}
+
+	const raw = await fs.readFile(configPath, "utf-8");
+	let config;
+
+	try {
+		config = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Invalid JSON in config file: ${configPath}\n${err.message}`);
+	}
+
+	if (!config.source_dir || typeof config.source_dir !== "string") {
+		throw new Error(`Config must include a "source_dir" string.`);
+	}
+
+	if (!Array.isArray(config.assets) || config.assets.length === 0) {
+		throw new Error(`Config must include a non-empty "assets" array.`);
+	}
+
+	for (const asset of config.assets) {
+		for (const field of ["name", "source", "destination"]) {
+			if (!asset[field] || typeof asset[field] !== "string") {
+				throw new Error(`Each asset must have a "${field}" string. Problem in: ${JSON.stringify(asset)}`);
+			}
+		}
+		if (!Array.isArray(asset.sizes) || asset.sizes.length === 0) {
+			throw new Error(`Asset "${asset.name}" must have a non-empty "sizes" array.`);
+		}
+	}
+
+	return config;
+}
+
+/**
+ * Default config template for `better-asset init`.
+ */
+export function defaultConfig() {
+	return {
+		$schema: "https://unpkg.com/better-asset/assets.config.schema.json",
+		source_dir: "public/assets",
+		assets: [
+			{
+				name: "icon",
+				source: "icon.svg",
+				sizes: [48, 96, 144, 512],
+				destination: "public/icons",
+			},
+			{
+				name: "favicon",
+				source: "favicon.svg",
+				sizes: [16, 32, 48],
+				destination: "public/icons",
+				ico: {
+					required: true,
+					size: 96,
+				},
+			},
+			{
+				name: "opengraph-image",
+				source: "icon.svg",
+				sizes: ["1200x630"],
+				destination: "public/icons",
+				format: "jpeg",
+			},
+		],
+	};
+}

package/src/fs-utils.js

@@ -0,0 +1,14 @@
+import fs from "fs/promises";
+
+export async function ensureDir(dir) {
+	await fs.mkdir(dir, { recursive: true });
+}
+
+export async function fileExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/generate.js

@@ -0,0 +1,57 @@
+import path from "path";
+import { resolveConfigPath, loadConfig } from "./config.js";
+import { ensureDir, fileExists } from "./fs-utils.js";
+import { parseSize, buildFileName, generateImage, generateIco } from "./image.js";
+import { cleanGeneratedFiles } from "./clean.js";
+import * as log from "./log.js";
+
+export async function generate(cwd, configFlag) {
+	const configPath = resolveConfigPath(cwd, configFlag);
+
+	log.banner();
+	log.configPath(path.relative(cwd, configPath) || configPath);
+
+	const config = await loadConfig(configPath);
+	const start = performance.now();
+	let totalFiles = 0;
+
+	for (const asset of config.assets) {
+		const sourcePath = path.join(cwd, config.source_dir, asset.source);
+		const destinationDir = path.join(cwd, asset.destination);
+
+		if (!(await fileExists(sourcePath))) {
+			log.warn(`Skipping ${asset.name} — source not found: ${asset.source}`);
+			continue;
+		}
+
+		log.groupStart(asset.name, asset.source);
+
+		await ensureDir(destinationDir);
+		await cleanGeneratedFiles(destinationDir, asset.name);
+
+		const totalSizes = asset.sizes.length;
+		const format = asset.format || "png";
+
+		for (const rawSize of asset.sizes) {
+			const { width, height, label } = parseSize(rawSize);
+			const fileName = buildFileName(asset.name, label, asset.sizeInName, totalSizes, format);
+			const outputPath = path.join(destinationDir, fileName);
+
+			await generateImage(sourcePath, outputPath, width, height, format);
+
+			log.success(fileName, `${width}×${height}`);
+			totalFiles++;
+		}
+
+		if (asset.ico?.required) {
+			const icoPath = path.join(destinationDir, "favicon.ico");
+			await generateIco(sourcePath, icoPath, asset.ico.size || 64);
+
+			log.success("favicon.ico", `${asset.ico.size || 64}×${asset.ico.size || 64}`);
+			totalFiles++;
+		}
+	}
+
+	const elapsed = Math.round(performance.now() - start);
+	log.done(totalFiles, elapsed);
+}

package/src/image.js

@@ -0,0 +1,48 @@
+import sharp from "sharp";
+import path from "path";
+
+export function parseSize(size) {
+	if (typeof size === "number") {
+		return { width: size, height: size, label: `${size}` };
+	}
+
+	if (typeof size === "string") {
+		const [w, h] = size.split("x").map(Number);
+		if (!w || !h) throw new Error(`Invalid size format: ${size}`);
+		return { width: w, height: h, label: `${w}x${h}` };
+	}
+
+	throw new Error(`Unsupported size type: ${size}`);
+}
+
+export function buildFileName(name, label, sizeInName, totalSizes, format) {
+	const includeSize = sizeInName === true || (sizeInName === undefined && totalSizes > 1);
+	const ext = format || "png";
+	return includeSize ? `${name}-${label}.${ext}` : `${name}.${ext}`;
+}
+
+export async function generateImage(inputPath, outputPath, width, height, format) {
+	let pipeline = sharp(inputPath).resize(width, height);
+
+	switch (format) {
+		case "webp":
+			pipeline = pipeline.webp();
+			break;
+		case "jpeg":
+		case "jpg":
+			pipeline = pipeline.jpeg();
+			break;
+		case "avif":
+			pipeline = pipeline.avif();
+			break;
+		default:
+			pipeline = pipeline.png();
+	}
+
+	await pipeline.toFile(outputPath);
+}
+
+export async function generateIco(inputPath, outputPath, size) {
+	const buffer = await sharp(inputPath).resize(size, size).png().toBuffer();
+	await sharp(buffer).toFormat("png").toFile(outputPath);
+}

package/src/log.js

@@ -0,0 +1,52 @@
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BLUE = "\x1b[34m";
+const MAGENTA = "\x1b[35m";
+const CYAN = "\x1b[36m";
+
+const CHECKMARK = `${GREEN}✔${RESET}`;
+const CROSS = `${RED}✖${RESET}`;
+const WARN = `${YELLOW}⚠${RESET}`;
+const ARROW = `${DIM}→${RESET}`;
+const DOT = `${DIM}·${RESET}`;
+
+export function banner() {
+	console.log();
+	console.log(`  ${BOLD}${MAGENTA}better-asset${RESET}  ${DIM}— config-driven image asset generator${RESET}`);
+	console.log();
+}
+
+export function info(msg) {
+	console.log(`  ${BLUE}info${RESET}  ${msg}`);
+}
+
+export function success(file, size) {
+	console.log(`  ${CHECKMARK}  ${file}  ${DIM}${size}${RESET}`);
+}
+
+export function warn(msg) {
+	console.log(`  ${WARN}  ${YELLOW}${msg}${RESET}`);
+}
+
+export function error(msg) {
+	console.error(`  ${CROSS}  ${RED}${msg}${RESET}`);
+}
+
+export function groupStart(name, source) {
+	console.log();
+	console.log(`  ${BOLD}${CYAN}${name}${RESET}  ${DIM}← ${source}${RESET}`);
+}
+
+export function done(count, elapsed) {
+	console.log();
+	console.log(`  ${CHECKMARK}  ${BOLD}${count} file${count === 1 ? "" : "s"}${RESET} generated ${DIM}in ${elapsed}ms${RESET}`);
+	console.log();
+}
+
+export function configPath(p) {
+	console.log(`  ${DOT} config  ${DIM}${p}${RESET}`);
+}