favgen 0.2.4 → 0.2.6

package/README.md

@@ -2,6 +2,8 @@
 
 This is a simple CLI tool to generate an optimized set of favicons from a single input file. Icons are optimized in terms of both size and quantity (nowadays you don't need that many of them). They are produced according to [this article](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) which served as an inspiration for the tool.
 
+## CLI usage
+
 Use it like this: `npx favgen /path/to/input -o /path/to/output`.
 
 You can tweak the following settings by giving additional commands:
@@ -23,6 +25,8 @@ Additionally, a sample `manifest.webmanifest` file is produced which includes re
 Besides that, PNG output is optimized by `sharp` (which uses `pngquant`) and SVG output is optimized by [SVGO](https://github.com/svg/svgo).
 Also, color palette is reduced to 64 colors by default in order to reduce assets’ size.
 
+## JS API usage
+
 The tool can be also used as API:
 ```js
 const { produceIcons } = require("favgen")
@@ -32,7 +36,14 @@ const paletteSize = 64 // default value
 produceIcons(inputFilePath, outputDirPath, paletteSize)
 ```
 
-Vite plugin usage:
+## Vite plugin usage
+
+Install:
+```bash
+npm i favgen
+```
+
+Configure in `vite.config.js` or `vite.config.ts`:
 ```js
 import { defineConfig } from "vite"
 import { favgenVitePlugin } from "favgen"
@@ -47,3 +58,67 @@ export default defineConfig({
   ],
 })
 ```
+
+Vite plugin options:
+- `source` (required): path to source image (SVG, PNG, JPEG, WebP, GIF, AVIF, TIFF)
+- `colors` (optional): PNG palette size between 2 and 256 (`64` by default)
+- `assetsPath` (optional): subdirectory where generated assets are emitted (e.g. `favicons`)
+
+The plugin runs on build and:
+- generates favicon assets using the same logic as CLI/API
+- emits them into the final build output
+- injects links into built HTML:
+  - `favicon.ico`
+  - `icon.svg` (only when source is SVG)
+  - `apple-touch-icon.png`
+  - `manifest.webmanifest`
+
+Generated files:
+- `icon.svg` (only for SVG source)
+- `favicon.ico`
+- `icon-192.png`
+- `icon-512.png`
+- `icon-mask.png`
+- `apple-touch-icon.png`
+- `manifest.webmanifest`
+
+Manifest icon URLs and injected HTML links are automatically adjusted for Vite `base` and `assetsPath` settings.
+
+## Webpack plugin usage
+
+Install:
+```bash
+npm i favgen
+```
+
+Configure in your webpack config:
+```js
+const FavgenWebpackPlugin = require("favgen").FavgenWebpackPlugin
+
+module.exports = {
+  // ...rest of config
+  plugins: [
+    new FavgenWebpackPlugin({
+      source: "src/assets/logo.svg",
+      colors: 64,
+      assetsPath: "favicons",
+    }),
+  ],
+}
+```
+
+Webpack plugin options:
+- `source` (required): path to source image (SVG, PNG, JPEG, WebP, GIF, AVIF, TIFF)
+- `colors` (optional): PNG palette size between 2 and 256 (`64` by default)
+- `assetsPath` (optional): subdirectory where generated assets are emitted (e.g. `favicons`)
+
+The plugin runs during webpack compilation and:
+- generates favicon assets using the same logic as CLI/API
+- emits assets into compilation output
+- injects links into generated `.html` assets:
+  - `favicon.ico`
+  - `icon.svg` (only when source is SVG)
+  - `apple-touch-icon.png`
+  - `manifest.webmanifest`
+
+Manifest icon URLs and injected HTML links are automatically adjusted for webpack `output.publicPath` and `assetsPath`.

package/lib/index.d.mts

@@ -1,5 +1,8 @@
 import produceIconsImport from "./generator.js";
 import favgenVitePluginImport from "./vite-plugin.js";
+import FavgenWebpackPluginImport from "./webpack-plugin.js";
 export declare const produceIcons: typeof produceIconsImport;
 export declare const favgenVitePlugin: typeof favgenVitePluginImport;
+export declare const FavgenWebpackPlugin: typeof FavgenWebpackPluginImport;
 export type { FavgenVitePluginOptions } from "./vite-plugin.js";
+export type { FavgenWebpackPluginOptions } from "./webpack-plugin.js";

package/lib/index.d.ts

@@ -1,3 +1,5 @@
 export { default as produceIcons } from "./generator";
 export { default as favgenVitePlugin } from "./vite-plugin";
+export { default as FavgenWebpackPlugin } from "./webpack-plugin";
 export type { FavgenVitePluginOptions } from "./vite-plugin";
+export type { FavgenWebpackPluginOptions } from "./webpack-plugin";

package/lib/index.js

@@ -3,9 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.favgenVitePlugin = exports.produceIcons = void 0;
+exports.FavgenWebpackPlugin = exports.favgenVitePlugin = exports.produceIcons = void 0;
 // eslint-disable-next-line import/prefer-default-export
 var generator_1 = require("./generator");
 Object.defineProperty(exports, "produceIcons", { enumerable: true, get: function () { return __importDefault(generator_1).default; } });
 var vite_plugin_1 = require("./vite-plugin");
 Object.defineProperty(exports, "favgenVitePlugin", { enumerable: true, get: function () { return __importDefault(vite_plugin_1).default; } });
+var webpack_plugin_1 = require("./webpack-plugin");
+Object.defineProperty(exports, "FavgenWebpackPlugin", { enumerable: true, get: function () { return __importDefault(webpack_plugin_1).default; } });

package/lib/index.mjs

@@ -1,11 +1,15 @@
 import produceIconsImport from "./generator.js";
 import favgenVitePluginImport from "./vite-plugin.js";
+import FavgenWebpackPluginImport from "./webpack-plugin.js";
 function normalizeDefaultExport(mod) {
-    return (typeof mod === "object" &&
-        mod !== null &&
-        "default" in mod)
-        ? mod.default
-        : mod;
+    let current = mod;
+    while (typeof current === "object" &&
+        current !== null &&
+        "default" in current) {
+        current = current.default;
+    }
+    return current;
 }
 export const produceIcons = normalizeDefaultExport(produceIconsImport);
 export const favgenVitePlugin = normalizeDefaultExport(favgenVitePluginImport);
+export const FavgenWebpackPlugin = normalizeDefaultExport(FavgenWebpackPluginImport);

package/lib/webpack-plugin.d.ts

@@ -0,0 +1,53 @@
+/// <reference types="node" />
+/// <reference types="node" />
+export declare type FavgenWebpackPluginOptions = {
+    source: string;
+    colors?: number;
+    assetsPath?: string;
+};
+declare type RawSource = {
+    source: () => string | Buffer;
+};
+declare type RawSourceConstructor = new (source: string | Buffer) => RawSource;
+declare type Compilation = {
+    assets: Record<string, RawSource>;
+    hooks: {
+        processAssets: {
+            tapPromise: (options: {
+                name: string;
+                stage: number;
+            }, callback: () => Promise<void>) => void;
+        };
+    };
+    emitAsset: (name: string, asset: RawSource) => void;
+    updateAsset: (name: string, asset: RawSource) => void;
+};
+declare type Compiler = {
+    options: {
+        context?: string;
+        output?: {
+            publicPath?: string | "auto";
+        };
+    };
+    hooks: {
+        thisCompilation: {
+            tap: (name: string, callback: (compilation: Compilation) => void) => void;
+        };
+    };
+    webpack: {
+        Compilation: {
+            PROCESS_ASSETS_STAGE_ADDITIONS: number;
+        };
+        sources: {
+            RawSource: RawSourceConstructor;
+        };
+    };
+};
+export default class FavgenWebpackPlugin {
+    private readonly sourcePath;
+    private readonly paletteSize;
+    private readonly assetsPath;
+    constructor(options: FavgenWebpackPluginOptions);
+    apply(compiler: Compiler): void;
+}
+export {};

package/lib/webpack-plugin.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const generator_1 = __importDefault(require("./generator"));
+function normalizeAssetsPath(rawPath) {
+    if (!rawPath) {
+        return "";
+    }
+    return rawPath.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function isValidPaletteSize(size) {
+    return Number.isInteger(size) && size >= 2 && size <= 256;
+}
+function normalizePublicPath(publicPath) {
+    if (!publicPath || publicPath === "auto") {
+        return "/";
+    }
+    return publicPath;
+}
+function getAssetUrl(publicPath, assetsPath, filename) {
+    const relativePath = assetsPath
+        ? path_1.default.posix.join(assetsPath, filename)
+        : filename;
+    const normalizedPublicPath = publicPath.trim();
+    if (normalizedPublicPath === "." || normalizedPublicPath === "./") {
+        return relativePath;
+    }
+    if (/^https?:\/\//.test(normalizedPublicPath)) {
+        return new URL(relativePath, normalizedPublicPath).toString();
+    }
+    const publicPathWithSlash = normalizedPublicPath.endsWith("/")
+        ? normalizedPublicPath
+        : `${normalizedPublicPath}/`;
+    return `${publicPathWithSlash}${relativePath}`;
+}
+function rewriteManifest(manifestBuffer, publicPath, assetsPath) {
+    const manifest = JSON.parse(manifestBuffer.toString("utf8"));
+    if (Array.isArray(manifest.icons)) {
+        manifest.icons = manifest.icons.map((icon) => {
+            const sourcePath = icon.src;
+            const iconFilename = typeof sourcePath === "string"
+                ? path_1.default.posix.basename(sourcePath)
+                : "";
+            return {
+                ...icon,
+                src: getAssetUrl(publicPath, assetsPath, iconFilename),
+            };
+        });
+    }
+    return Buffer.from(JSON.stringify(manifest, null, 2));
+}
+function getHtmlTagStrings(publicPath, assetsPath, hasSvgIcon) {
+    const tags = [
+        `<link rel="icon" href="${getAssetUrl(publicPath, assetsPath, "favicon.ico")}" sizes="any">`,
+        `<link rel="apple-touch-icon" href="${getAssetUrl(publicPath, assetsPath, "apple-touch-icon.png")}">`,
+        `<link rel="manifest" href="${getAssetUrl(publicPath, assetsPath, "manifest.webmanifest")}">`,
+    ];
+    if (hasSvgIcon) {
+        tags.splice(1, 0, `<link rel="icon" href="${getAssetUrl(publicPath, assetsPath, "icon.svg")}" type="image/svg+xml">`);
+    }
+    return tags;
+}
+function injectTagsIntoHtml(htmlText, tags) {
+    const missingTags = tags.filter((tag) => !htmlText.includes(tag));
+    if (missingTags.length === 0) {
+        return htmlText;
+    }
+    const tagsBlock = `${missingTags.join("\n")}\n`;
+    if (/<\/head>/i.test(htmlText)) {
+        return htmlText.replace(/<\/head>/i, `${tagsBlock}</head>`);
+    }
+    return `${tagsBlock}${htmlText}`;
+}
+class FavgenWebpackPlugin {
+    constructor(options) {
+        this.sourcePath = options.source;
+        this.paletteSize = options.colors ?? 64;
+        this.assetsPath = normalizeAssetsPath(options.assetsPath);
+    }
+    apply(compiler) {
+        compiler.hooks.thisCompilation.tap("favgen-webpack-plugin", (compilation) => {
+            const stage = compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS;
+            const { RawSource } = compiler.webpack.sources;
+            compilation.hooks.processAssets.tapPromise({ name: "favgen-webpack-plugin", stage }, async () => {
+                if (!this.sourcePath || this.sourcePath.trim().length === 0) {
+                    throw new Error("favgen-webpack-plugin: `source` option is required.");
+                }
+                if (!isValidPaletteSize(this.paletteSize)) {
+                    throw new Error("favgen-webpack-plugin: `colors` must be an integer between 2 and 256.");
+                }
+                const projectRoot = compiler.options.context ?? process.cwd();
+                const publicPath = normalizePublicPath(compiler.options.output?.publicPath);
+                const resolvedSourcePath = path_1.default.isAbsolute(this.sourcePath)
+                    ? this.sourcePath
+                    : path_1.default.resolve(projectRoot, this.sourcePath);
+                const tempDirPath = await promises_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), "favgen-webpack-"));
+                try {
+                    await (0, generator_1.default)(resolvedSourcePath, tempDirPath, this.paletteSize);
+                    const iconFilenames = (await promises_1.default.readdir(tempDirPath)).sort();
+                    const hasSvgIcon = iconFilenames.includes("icon.svg");
+                    const generatedAssets = await Promise.all(iconFilenames.map(async (filename) => ({
+                        filename,
+                        source: await promises_1.default.readFile(path_1.default.join(tempDirPath, filename)),
+                    })));
+                    generatedAssets.forEach((asset) => {
+                        const outputFilename = this.assetsPath
+                            ? path_1.default.posix.join(this.assetsPath, asset.filename)
+                            : asset.filename;
+                        const outputSource = asset.filename === "manifest.webmanifest"
+                            ? rewriteManifest(asset.source, publicPath, this.assetsPath)
+                            : asset.source;
+                        compilation.emitAsset(outputFilename, new RawSource(outputSource));
+                    });
+                    const htmlTags = getHtmlTagStrings(publicPath, this.assetsPath, hasSvgIcon);
+                    Object.entries(compilation.assets).forEach(([filename, asset]) => {
+                        if (!filename.endsWith(".html")) {
+                            return;
+                        }
+                        const currentSource = asset.source();
+                        const htmlText = Buffer.isBuffer(currentSource)
+                            ? currentSource.toString("utf8")
+                            : String(currentSource);
+                        const nextHtmlText = injectTagsIntoHtml(htmlText, htmlTags);
+                        if (nextHtmlText !== htmlText) {
+                            compilation.updateAsset(filename, new RawSource(nextHtmlText));
+                        }
+                    });
+                }
+                finally {
+                    await promises_1.default.rm(tempDirPath, { recursive: true, force: true });
+                }
+            });
+        });
+    }
+}
+exports.default = FavgenWebpackPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "favgen",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "CLI tool to generate a set of favicons from a single input file.",
   "keywords": [
     "favicon"
@@ -25,11 +25,15 @@
     "bin/"
   ],
   "peerDependencies": {
-    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "webpack": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "vite": {
       "optional": true
+    },
+    "webpack": {
+      "optional": true
     }
   },
   "engines": {