vite-plugin-css-svg-mask-image 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# vite-plugin-css-svg-mask-image
+
+A Vite plugin that rewrites `mask-image: svg(...)` calls in your CSS/SCSS into a complete, cross-browser mask setup (mask image, repeat, size, and optional color via background-color). It also generates a single `icons.scss` file with `:root` CSS variables for each SVG icon, so the SVG data is stored once and reused everywhere, no duplicated inline SVG blobs across your stylesheets.
+
+Best used with icons that are a single compound shape (solid silhouette). Multi-shape or multi-color SVGs can produce unexpected masking results.
+
+## Description
+
+This plugin processes CSS and SCSS files to transform `mask-image: svg()` function calls into standard CSS mask properties. It automatically:
+
+- Converts SVG files to data URIs
+- Generates CSS variables in `:root` for each icon
+- Replaces `svg()` calls with the appropriate CSS properties
+- Writes the `:root` declarations to a separate file (default: `icons.scss`)
+
+## Installation
+
+```bash
+npm install vite-plugin-css-svg-mask-image --save-dev
+```
+
+### Basic Setup
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { svgMaskPlugin } from "vite-plugin-css-svg-mask-image";
+
+export default defineConfig({
+  plugins: [
+    svgMaskPlugin({
+      svg_dir: "src/icons", // Directory containing SVG files
+      icons_file: "icons.scss", // Output file for :root declarations
+    }),
+  ],
+});
+```
+
+### Configuration Options
+
+- `svg_dir` (string, optional): Directory where SVG files are stored. Default: `'src/icons'`
+- `icons_file` (string, optional): Path to the output file containing `:root` declarations. Default: `'icons.scss'`
+
+### CSS/SCSS Usage
+
+In your CSS or SCSS files, use the `svg()` function:
+
+```scss
+.a {
+  mask-image: svg("arrow-right");
+}
+
+.b {
+  mask-image: svg("arrow-right", "red");
+}
+```
+
+The plugin will transform this to:
+
+```scss
+:root {
+  --icon-arrow-right: url("data:image/svg+xml,...");
+}
+
+.a {
+  background-color: currentColor;
+  mask-image: var(--icon-arrow-right);
+  mask-repeat: no-repeat;
+  mask-size: 100% 100%;
+}
+
+.b {
+  background-color: red;
+  mask-image: var(--icon-arrow-right);
+  mask-repeat: no-repeat;
+  mask-size: 100% 100%;
+}
+```
+
+The `:root` declarations are automatically written to the `icons.scss` file (or your configured output file). Make sure to import this file in your main stylesheet.
+
+## Requirements
+
+- Vite 4.0+ or 5.0+
+- Node.js 22+
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+export interface SvgMaskPluginOptions {
+    svg_dir?: string;
+    icons_file?: string;
+}
+export declare function svgMaskPlugin(options?: SvgMaskPluginOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,142 @@
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
+import { join, resolve, dirname } from "path";
+import postcss, { Declaration } from "postcss";
+function parse_svg_function(value) {
+    const match = value.match(/^['"]?([^'",]+)['"]?\s*(?:,\s*['"]?([^'"]+)['"]?)?$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        name: match[1].trim(),
+        color: match[2]?.trim(),
+    };
+}
+function to_kebab_name(input) {
+    // basename without extension -> kebab-ish
+    return input
+        .replace(/\.[a-z0-9]+$/i, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+function svg_to_data_uri(svg) {
+    const cleaned = svg.replace(/^\uFEFF/, "").trim();
+    const encoded = encodeURIComponent(cleaned)
+        .replace(/%0A/g, "")
+        .replace(/%0D/g, "")
+        .replace(/%20/g, " ")
+        .replace(/%3D/g, "=")
+        .replace(/%3A/g, ":")
+        .replace(/%2F/g, "/");
+    return `data:image/svg+xml,${encoded}`;
+}
+function get_css_variable_name(icon_name) {
+    const kebab_name = to_kebab_name(icon_name);
+    return `--icon-${kebab_name}`;
+}
+export function svgMaskPlugin(options = {}) {
+    const svg_dir = options.svg_dir || "src/icons";
+    const icons_file = options.icons_file || "icons.scss";
+    const root_dir = process.cwd();
+    const resolved_svg_dir = resolve(root_dir, svg_dir);
+    const resolved_icons_file = resolve(root_dir, icons_file);
+    const icon_variables = new Map();
+    const processed_files = new Set();
+    const write_icons_file = () => {
+        const icons_dir = dirname(resolved_icons_file);
+        if (!existsSync(icons_dir)) {
+            mkdirSync(icons_dir, { recursive: true });
+        }
+        if (icon_variables.size === 0) {
+            if (!existsSync(resolved_icons_file)) {
+                writeFileSync(resolved_icons_file, ":root {\n}\n", "utf-8");
+            }
+            return;
+        }
+        let root_content = ":root {\n";
+        for (const [name, data_uri] of icon_variables.entries()) {
+            const var_name = get_css_variable_name(name);
+            root_content += `  ${var_name}: url("${data_uri}");\n`;
+        }
+        root_content += "}\n";
+        writeFileSync(resolved_icons_file, root_content, "utf-8");
+    };
+    return {
+        name: "vite-plugin-css-svg-mask-image",
+        enforce: "pre",
+        buildStart() {
+            const icons_dir = dirname(resolved_icons_file);
+            if (!existsSync(icons_dir)) {
+                mkdirSync(icons_dir, { recursive: true });
+            }
+            if (!existsSync(resolved_icons_file)) {
+                writeFileSync(resolved_icons_file, ":root {\n}\n", "utf-8");
+            }
+        },
+        async transform(code, id) {
+            if (!id.match(/\.(css|scss|sass)$/)) {
+                return null;
+            }
+            const ast = postcss.parse(code);
+            let has_svg_functions = false;
+            ast.walkDecls("mask-image", (decl) => {
+                const value = decl.value.trim();
+                if (!value.startsWith("svg(")) {
+                    return;
+                }
+                const match = value.match(/^svg\(([^)]+)\)$/);
+                if (!match) {
+                    return;
+                }
+                const parsed = parse_svg_function(match[1]);
+                if (!parsed) {
+                    return;
+                }
+                const { name, color } = parsed;
+                const svg_path = join(resolved_svg_dir, `${name}.svg`);
+                if (!existsSync(svg_path)) {
+                    console.warn(`[vite-plugin-css-svg-mask-image] SVG file not found: ${svg_path}`);
+                    return;
+                }
+                const svg_content = readFileSync(svg_path, "utf-8");
+                const data_uri = svg_to_data_uri(svg_content);
+                const var_name = get_css_variable_name(name);
+                icon_variables.set(name, data_uri);
+                has_svg_functions = true;
+                const rule = decl.parent;
+                if (rule && rule.type === "rule") {
+                    decl.value = `var(${var_name})`;
+                    const bg_color = color || "currentColor";
+                    const has_bg_color = rule.nodes?.some((node) => node.type === "decl" && node.prop === "background-color");
+                    if (!has_bg_color) {
+                        rule.insertAfter(decl, new Declaration({ prop: "background-color", value: bg_color }));
+                    }
+                    const has_mask_repeat = rule.nodes?.some((node) => node.type === "decl" && node.prop === "mask-repeat");
+                    if (!has_mask_repeat) {
+                        rule.insertAfter(decl, new Declaration({ prop: "mask-repeat", value: "no-repeat" }));
+                    }
+                    const has_mask_size = rule.nodes?.some((node) => node.type === "decl" && node.prop === "mask-size");
+                    if (!has_mask_size) {
+                        rule.insertAfter(decl, new Declaration({ prop: "mask-size", value: "100% 100%" }));
+                    }
+                }
+            });
+            if (!has_svg_functions) {
+                return null;
+            }
+            const result = await postcss().process(ast, { from: id, to: id });
+            processed_files.add(id);
+            return {
+                code: result.css,
+                map: result.map ? result.map.toJSON() : null,
+            };
+        },
+        buildEnd() {
+            write_icons_file();
+        },
+        generateBundle() {
+            write_icons_file();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "vite-plugin-css-svg-mask-image",
+  "version": "1.0.0",
+  "description": "Vite plugin to transform CSS/SCSS files with svg() mask-image function calls to CSS variables",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "svg",
+    "mask",
+    "css",
+    "scss"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "postcss": "^8.5.6"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0"
+  }
+}