images2atlas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Porky Ke
+
+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,95 @@
+# images2atlas
+
+Generate a spritesheet atlas and matching style/template output from a directory
+of PNG images. This module scans folders recursively, copies non-PNG files as-is,
+and produces atlas files per directory with configurable formats and suffixes.
+
+## Core Features
+Use these features to understand what the tool produces and how it behaves.
+- Directory-based spritesheet generation (one atlas per folder).
+- Recursive traversal with include/exclude filters.
+- Copies non-PNG files into the destination tree.
+- Multiple template formats via [`spritesheet-templates`](https://github.com/twolfson/spritesheet-templates).
+- Optional watch mode with debounced re-pack on changes.
+
+## Installation
+```
+npm i images2atlas --save-dev
+```
+
+## Usage
+```ts
+import { images2atlas } from 'images2atlas';
+
+await images2atlas({
+  src: '/path/to/icons',
+  dest: '/path/to/output/icons',
+});
+```
+
+## Options
+Use these options to control inputs, outputs, and packing behavior.
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | required | Source directory containing images. Must be a directory. |
+| `dest` | `string` | required | Destination directory (no file extension). |
+| `exclude` | `(info, src) => boolean` | `() => false` | Return `true` to skip a file or folder. |
+| `include` | `(info, src) => boolean` | `() => true` | Return `true` to include a PNG in the atlas. |
+| `suffix` | `string` | `-atlas` | Output suffix for atlas files. |
+| `delay` | `number` | `500` | Debounce delay (ms) for watch mode. |
+| `silent` | `boolean` | `true` | Suppress logging when `true`. |
+| `watch` | `boolean` | `false` | Watch `src` and re-pack on changes. |
+| `spritesmithOptions` | `object` | `{ padding: 2, exportOpts: { format: 'png', quality: 100 } }` | Options passed to [`spritesmith`](https://github.com/twolfson/spritesmith). |
+| `templatesOptions` | `object` | `{ format: 'css' }` | Options passed to [`spritesheet-templates`](https://github.com/twolfson/spritesheet-templates?tab=readme-ov-file). |
+
+## Output Behavior
+Each directory with PNG files generates a pair of outputs in its corresponding
+`dest` folder:
+
+- `${src}${suffix}.png` (the atlas image)
+- `${src}${suffix}.<ext>` (template output)
+
+The template file extension is derived from `templatesOptions.format`, supporting:
+`css`, `json`, `less`, `sass`, `scss`, `styl` and [`custom format`](https://github.com/twolfson/spritesheet-templates?tab=readme-ov-file#custom).
+The format check is a prefix match, so `styl` also matches formats like
+`stylus`.
+
+The spritesheet image reference in templates uses the pattern:
+```
+<dest-dir-name><suffix>.png
+```
+If a directory contains no PNG files, no atlas or template files are generated
+for that directory.
+
+## Example Structure
+Input:
+```
+src/
+└── icons/
+    ├── a.png
+    ├── b.png
+    └── bg.jpg
+```
+
+Output (with `suffix: '-atlas'` and `format: 'css'`):
+```
+dest/
+├── icons-atlas.png
+├── icons-atlas.css
+└── icons/
+    └── bg.jpg
+```
+
+## Notes
+Use these notes to understand how filters and paths are interpreted.
+- Only `.png` files are packed into the atlas. Non-PNG files are copied through.
+- `include` only affects whether a PNG participates in the atlas. If `include`
+  returns `false`, the PNG is copied instead.
+- `exclude` skips both atlas participation and file copying for the matched path.
+- `src` must exist and be a directory path with no file extension.
+- `dest` must be a directory path with no file extension.
+- Filenames are filtered via `isSafeFilename` from [`web-build-utils`](https://github.com/porky-prince/web-build-tools/packages/web-build-utils).
+
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md) for release history.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import path from 'path';
+import templater from 'spritesheet-templates';
+import Spritesmith from 'spritesmith';
+/**
+ * Options for Images2atlas
+ *
+ * @property {string} src - The source directory containing images to pack. Must be a directory.
+ * @property {string} dest - The destination directory for output files. Must be a directory.
+ * @property {function} [exclude] - Function to exclude files/directories from packing. Receives parsed path info and full path. Return true to exclude.
+ * @property {function} [include] - Function to include files/directories for packing. Receives parsed path info and full path. Return true to include.
+ * @property {string} [suffix] - Suffix for output files (e.g., '-atlas'). Default is '-atlas'.
+ * @property {number} [delay] - Debounce delay (ms) for packing after changes. Default is 500ms.
+ * @property {boolean} [silent] - If true, suppresses plugin logging. Default is true.
+ * @property {boolean} [watch] - If true, watch src and re-pack on changes. Default is false.
+ * @property {object} [spritesmithOptions] - Options for Spritesmith (e.g., padding, export format, quality).
+ * @property {object} [templatesOptions] - Options for spritesheet-templates (e.g., output format, custom templates).
+ */
+export interface Images2atlasOptions {
+    src: string;
+    dest: string;
+    exclude?: (srcInfo: path.ParsedPath, src: string) => boolean;
+    include?: (srcInfo: path.ParsedPath, src: string) => boolean;
+    suffix?: string;
+    delay?: number;
+    silent?: boolean;
+    watch?: boolean;
+    spritesmithOptions?: Spritesmith.SpritesmithParams & Spritesmith.SpritesmithProcessImagesOptions;
+    templatesOptions?: Parameters<typeof templater>[1];
+}
+export declare function images2atlas(options: Images2atlasOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,179 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.images2atlas = images2atlas;
+const chokidar_1 = require("chokidar");
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const spritesheet_templates_1 = __importDefault(require("spritesheet-templates"));
+const spritesmith_1 = __importDefault(require("spritesmith"));
+const debounce_1 = __importDefault(require("debounce"));
+const web_build_utils_1 = require("web-build-utils");
+// Supported output template formats for spritesheet-templates.
+const formatTypes = ['css', 'json', 'less', 'sass', 'scss', 'styl'];
+/**
+ * Images2atlas
+ *
+ * Plugin to generate a spritesheet atlas and style/template files from a directory of PNG images.
+ * Automatically watches for changes and repacks as needed.
+ */
+class Images2atlas {
+    /**
+     * Constructor
+     * Validates and initializes plugin options.
+     * Throws error if src or dest are not directories.
+     */
+    constructor(options) {
+        // File watcher instance
+        this._watcher = null;
+        if (!fs_extra_1.default.existsSync(options.src) ||
+            !fs_extra_1.default.statSync(options.src).isDirectory()) {
+            throw new Error('The options.src must be a directory.');
+        }
+        if (path_1.default.extname(options.dest)) {
+            throw new Error('The options.dest must be a directory.');
+        }
+        this._options = Object.assign({ exclude: () => false, include: () => true, suffix: '-atlas', delay: 500, silent: true, watch: false, spritesmithOptions: {
+                padding: 2,
+                exportOpts: {
+                    format: 'png',
+                    quality: 100,
+                },
+            }, templatesOptions: {} }, options);
+    }
+    /**
+     * Logs messages using console if not silent.
+     */
+    log(...args) {
+        if (this._options.silent) {
+            return;
+        }
+        console.log(...args);
+    }
+    /**
+     * Initializes and returns a file watcher for the source directory.
+     * Calls the provided callback on file events.
+     */
+    getWatcher(cb) {
+        if (!this._watcher) {
+            fs_extra_1.default.ensureDirSync(this._options.src);
+            this._watcher = (0, chokidar_1.watch)('.', {
+                cwd: this._options.src,
+                ignoreInitial: true,
+            });
+            this._watcher.on('all', cb);
+        }
+        return this._watcher;
+    }
+    runPack() {
+        const { src, dest, delay, watch } = this._options;
+        const pack = () => this.pack(src, dest);
+        if (watch) {
+            // Debounce to avoid re-packing on bursty file events.
+            const delayPack = (0, debounce_1.default)(pack, delay);
+            this.getWatcher((e, p) => {
+                if (!(0, web_build_utils_1.isSafeFilename)(p, true)) {
+                    return;
+                }
+                this.log(e, p);
+                delayPack();
+            });
+        }
+        return pack();
+    }
+    /**
+     * Packs images from the source directory into the destination directory.
+     * Recursively processes files and directories, collects PNGs for spritesheet, copies other files.
+     * @param src Source directory
+     * @param dest Destination directory
+     */
+    pack(src, dest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.log('pack', src);
+            const { exclude, include } = this._options;
+            const fullNames = yield fs_extra_1.default.readdir(src);
+            const pngPaths = [];
+            yield Promise.all(fullNames.map((fullName) => __awaiter(this, void 0, void 0, function* () {
+                const srcPath = path_1.default.join(src, fullName);
+                const info = path_1.default.parse(srcPath);
+                if (!(0, web_build_utils_1.isSafeFilename)(srcPath, true) || exclude(info, srcPath)) {
+                    return;
+                }
+                const destPath = path_1.default.join(dest, info.base);
+                if (info.ext) {
+                    // File
+                    if (info.ext === '.png' && include(info, srcPath)) {
+                        // Collect PNGs for atlas generation later.
+                        pngPaths.push(srcPath);
+                    }
+                    else {
+                        // Copy single file
+                        yield fs_extra_1.default.outputFile(destPath, yield fs_extra_1.default.readFile(srcPath));
+                    }
+                }
+                else {
+                    // Dir
+                    yield this.pack(srcPath, destPath);
+                }
+            })));
+            // Generate atlas and template outputs for collected PNGs.
+            yield this.packSpriteSheet(pngPaths, dest);
+            this.log('packed', dest);
+        });
+    }
+    /**
+     * Generates the spritesheet and style/template files from collected PNG paths.
+     * Uses Spritesmith to create the atlas and spritesheet-templates for output files.
+     * @param pngPaths Array of PNG image paths
+     * @param dest Destination directory
+     */
+    packSpriteSheet(pngPaths, dest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (pngPaths.length === 0) {
+                return;
+            }
+            const { suffix, spritesmithOptions, templatesOptions } = this._options;
+            const format = templatesOptions.format || 'css';
+            yield new Promise((resolve, reject) => {
+                spritesmith_1.default.run(Object.assign(Object.assign({}, spritesmithOptions), { src: pngPaths }), (err, result) => __awaiter(this, void 0, void 0, function* () {
+                    if (err) {
+                        return reject(err);
+                    }
+                    // Map image coordinates to sprite objects
+                    const sprites = Object.keys(result.coordinates).map((imgPath) => {
+                        const info = path_1.default.parse(imgPath);
+                        return Object.assign(Object.assign({}, result.coordinates[imgPath]), { name: info.name });
+                    });
+                    // Spritesheet properties and output image path
+                    const spritesheet = Object.assign(Object.assign({}, result.properties), { image: `${path_1.default.basename(dest) + suffix}.png` });
+                    // Generate template/style file
+                    const temp = (0, spritesheet_templates_1.default)({
+                        sprites,
+                        spritesheet,
+                    }, templatesOptions);
+                    // Determine output file extension
+                    const ext = formatTypes.find((type) => format.startsWith(type)) || format;
+                    yield Promise.all([
+                        fs_extra_1.default.outputFile(dest + suffix + '.' + ext, temp),
+                        fs_extra_1.default.outputFile(dest + suffix + '.png', result.image),
+                    ]);
+                    resolve();
+                }));
+            });
+        });
+    }
+}
+function images2atlas(options) {
+    return new Images2atlas(options).runPack();
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "images2atlas",
+  "version": "1.0.0",
+  "description": "Plugin that converts set of images into a spritesheet by its directory and SASS/LESS/Stylus mixins",
+  "author": "Porky Ke",
+  "homepage": "https://github.com/porky-prince/web-build-tools/packages/images2atlas#readme",
+  "bugs": "https://github.com/porky-prince/web-build-tools/issues",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "spritesheet-templates.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:porky-prince/web-build-tools.git",
+    "directory": "packages/images2atlas"
+  },
+  "dependencies": {
+    "@types/spritesmith": "^3.4.5",
+    "chokidar": "^4.0.3",
+    "debounce": "^2.2.0",
+    "fs-extra": "^11.3.2",
+    "spritesheet-templates": "^10.5.2",
+    "spritesmith": "^3.5.1",
+    "web-build-utils": "^0.0.4"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.6.2"
+  },
+  "keywords": [
+    "icons",
+    "images",
+    "sprites",
+    "spritesmith"
+  ],
+  "scripts": {
+    "start": "tsc -w",
+    "tsc": "tsc --declaration",
+    "build": "del dist && npm run tsc",
+    "test": "jest"
+  }
+}

package/spritesheet-templates.d.ts

@@ -0,0 +1,10 @@
+declare module 'spritesheet-templates' {
+  interface Options {
+    // spritesheetName?: string;
+    format?: string;
+    formatOpts?: Record<string, any>;
+  }
+
+  function templater(data: any, options: Options): string;
+  export = templater;
+}