svger-cli 1.0.0

package/.svg-lock

@@ -0,0 +1 @@
+[]

package/README.md

@@ -0,0 +1,121 @@
+svger-cli CLI Commands Reference
+
+Version: 1.0.0
+Purpose: Convert SVGs into React components with configurable defaults, watch mode, and selective rebuilding.
+
+1. Build Command
+Command	Example
+svger-cli build [options]	svger-cli build --src ./src/assets/svg --out ./src/components/icons
+
+What It Does
+
+Converts every .svg in the source folder into a React component.
+
+Applies default width, height, fill, and style rules from .svgconfig.json if present.
+
+Skips locked files.
+
+Generates component names based on PascalCase (configurable).
+
+2. Watch Command
+Command	Example
+svger-cli watch [options]	svger-cli watch --src ./src/assets/svg --out ./src/components/icons
+
+What It Does
+
+Continuously monitors the source folder for new, updated, or deleted SVG files.
+
+Automatically rebuilds React components for added or modified files.
+
+Deletes components if SVG files are removed.
+
+Skips locked files.
+
+Ideal for development with frequent SVG updates.
+
+3. Generate Command
+Command	Example
+svger-cli generate <svgFile> [options]	svger-cli generate ./src/assets/svg/heart.svg --out ./src/components/icons
+
+What It Does
+
+Converts a specific SVG file into a React component.
+
+Useful for adding a single icon to an existing collection.
+
+Honors default configuration values.
+
+4. Lock Command
+Command	Example
+svger-cli lock <svgFile> [options]	svger-cli lock ./src/assets/svg/logo.svg
+
+What It Does
+
+Marks one or more SVG files as locked.
+
+Locked files are skipped during build or watch operations.
+
+Ensures that branded or protected icons remain unchanged.
+
+5. Unlock Command
+Command	Example
+svger-cli unlock <svgFile> [options]	svger-cli unlock ./src/assets/svg/logo.svg
+
+What It Does
+
+Removes files from the locked state.
+
+Locked files can now be rebuilt normally.
+
+6. Config Command
+Command	Example
+svger-cli config [options]	svger-cli config --init or svger-cli config --set defaultWidth=32
+
+What It Does
+
+Creates or modifies .svgconfig.json for default build settings.
+
+--init — creates a new configuration file.
+
+--set <key=value> — updates configuration properties like source, output, defaultWidth, defaultHeight, defaultFill, etc.
+
+--show — displays current configuration.
+
+7. Clean Command
+Command	Example
+svger-cli clean --out <folder>	svger-cli clean --out ./src/components/icons
+
+What It Does
+
+Deletes all previously generated React component files in the specified output folder.
+
+Useful for rebuilding everything from scratch.
+
+8. Full One-Line Command (Bash / PowerShell / Mac / Linux)
+svger-cli config --init && \
+svger-cli config --set source=./src/assets/svg && \
+svger-cli config --set output=./src/components/icons && \
+svger-cli config --set defaultWidth=24 && \
+svger-cli config --set defaultHeight=24 && \
+svger-cli config --set defaultFill=currentColor && \
+svger-cli lock ./src/assets/svg/logo.svg && \
+svger-cli build ./src/assets/svg ./src/components/icons && \
+svger-cli generate ./src/assets/svg/new-icon.svg ./src/components/icons && \
+svger-cli unlock ./src/assets/svg/logo.svg && \
+svger-cli watch ./src/assets/svg ./src/components/icons && \
+svger-cli clean ./src/components/icons
+
+
+What It Does
+
+Initializes configuration, sets defaults, locks specific icons.
+
+Builds all SVGs, generates a new one, unlocks, and starts watch mode.
+
+Cleans output folder at the end if needed.
+
+
+
+Acknowledgements
+
+This project was implemented by Faeze Mohadespor, following the ADR authored by Navid Rezadoost and based on the TDR prepared by Ehsan Jafari. Their guidance and documentation on SVG integration methods in React were instrumental in shaping the design and functionality of the svger-cli CLI.

package/bin/svg-tool.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/builder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Converts all SVG files from a source directory into React components and writes them to an output directory.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {string} config.src - Path to the source folder containing SVG files.
+ * @param {string} config.out - Path to the output folder where React components will be generated.
+ * @returns {Promise<void>} Resolves when all SVGs have been processed.
+ */
+export declare function buildAll(config: {
+    src: string;
+    out: string;
+}): Promise<void>;
+/**
+ * Generates a single React component from an SVG file.
+ *
+ * @param {Object} params - Parameters object.
+ * @param {string} params.svgFile - Path to the SVG file to be converted.
+ * @param {string} params.outDir - Path to the output folder for the generated component.
+ * @returns {Promise<void>} Resolves when the SVG has been converted.
+ */
+export declare function generateSVG({ svgFile, outDir, }: {
+    svgFile: string;
+    outDir: string;
+}): Promise<void>;

package/dist/builder.js

@@ -0,0 +1,83 @@
+import fs from "fs-extra";
+import path from "path";
+import { pascalCase } from "change-case";
+import { reactTemplate } from "./templates/ComponentTemplate.js";
+import { isLocked } from "./lock.js";
+import { readConfig } from "./config.js";
+/**
+ * Converts all SVG files from a source directory into React components and writes them to an output directory.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {string} config.src - Path to the source folder containing SVG files.
+ * @param {string} config.out - Path to the output folder where React components will be generated.
+ * @returns {Promise<void>} Resolves when all SVGs have been processed.
+ */
+export async function buildAll(config) {
+    const svgConfig = readConfig();
+    const srcDir = path.resolve(config.src);
+    const outDir = path.resolve(config.out);
+    if (!fs.existsSync(srcDir)) {
+        console.error("❌ Source folder not found:", srcDir);
+        process.exit(1);
+    }
+    await fs.ensureDir(outDir);
+    const files = (await fs.readdir(srcDir)).filter(f => f.endsWith(".svg"));
+    if (!files.length) {
+        console.log("⚠️  No SVG files found in", srcDir);
+        return;
+    }
+    for (const file of files) {
+        const svgPath = path.join(srcDir, file);
+        if (isLocked(svgPath)) {
+            console.log(`⚠️ Skipped locked file: ${file}`);
+            continue;
+        }
+        const svgContent = await fs.readFile(svgPath, "utf-8");
+        const componentName = pascalCase(file.replace(".svg", ""));
+        const componentCode = reactTemplate({
+            componentName,
+            svgContent,
+            defaultWidth: svgConfig.defaultWidth,
+            defaultHeight: svgConfig.defaultHeight,
+            defaultFill: svgConfig.defaultFill,
+        });
+        const outFile = path.join(outDir, `${componentName}.tsx`);
+        await fs.writeFile(outFile, componentCode, "utf-8");
+        console.log(`✅ Generated: ${componentName}.tsx`);
+    }
+    console.log("🎉 All SVGs have been converted successfully!");
+}
+/**
+ * Generates a single React component from an SVG file.
+ *
+ * @param {Object} params - Parameters object.
+ * @param {string} params.svgFile - Path to the SVG file to be converted.
+ * @param {string} params.outDir - Path to the output folder for the generated component.
+ * @returns {Promise<void>} Resolves when the SVG has been converted.
+ */
+export async function generateSVG({ svgFile, outDir, }) {
+    const svgConfig = readConfig();
+    const filePath = path.resolve(svgFile);
+    if (isLocked(filePath)) {
+        console.log(`⚠️ Skipped locked file: ${path.basename(svgFile)}`);
+        return;
+    }
+    if (!fs.existsSync(filePath)) {
+        console.error("❌ SVG file not found:", filePath);
+        process.exit(1);
+    }
+    const svgContent = await fs.readFile(filePath, "utf-8");
+    const componentName = pascalCase(path.basename(svgFile, ".svg"));
+    const componentCode = reactTemplate({
+        componentName,
+        svgContent,
+        defaultWidth: svgConfig.defaultWidth,
+        defaultHeight: svgConfig.defaultHeight,
+        defaultFill: svgConfig.defaultFill,
+    });
+    const outputFolder = path.resolve(outDir);
+    await fs.ensureDir(outputFolder);
+    const outFile = path.join(outputFolder, `${componentName}.tsx`);
+    await fs.writeFile(outFile, componentCode, "utf-8");
+    console.log(`✅ Generated: ${componentName}.tsx`);
+}

package/dist/clean.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cleans the specified output directory by removing all files and folders inside it.
+ * Typically used to clear previously generated SVG React components before a new build.
+ *
+ * @param {string} outDir - Path to the output directory to be cleaned.
+ * @returns {Promise<void>} Resolves when the directory has been emptied.
+ */
+export declare function clean(outDir: string): Promise<void>;

package/dist/clean.js

@@ -0,0 +1,18 @@
+import fs from "fs-extra";
+import path from "path";
+/**
+ * Cleans the specified output directory by removing all files and folders inside it.
+ * Typically used to clear previously generated SVG React components before a new build.
+ *
+ * @param {string} outDir - Path to the output directory to be cleaned.
+ * @returns {Promise<void>} Resolves when the directory has been emptied.
+ */
+export async function clean(outDir) {
+    const targetDir = path.resolve(outDir);
+    if (!fs.existsSync(targetDir)) {
+        console.log(`⚠️ Directory not found: ${targetDir}`);
+        return;
+    }
+    await fs.emptyDir(targetDir);
+    console.log(`🧹 Cleaned all generated SVG components in: ${targetDir}`);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { buildAll, generateSVG } from "./builder.js";
+import { lockFiles, unlockFiles } from "./lock.js";
+import { initConfig, setConfig, showConfig } from "./config.js";
+import { watchSVGs } from "./watch.js";
+import { clean } from "./clean.js";
+const program = new Command();
+/**
+ * svger-cli CLI
+ * Custom SVG to React component converter.
+ */
+program
+    .name("svger-cli")
+    .description("Custom SVG to React component converter")
+    .version("1.0.0");
+// -------- Build Command --------
+/**
+ * Build all SVGs from a source folder to an output folder.
+ *
+ * @param {string} src - Source folder containing SVG files.
+ * @param {string} out - Output folder for generated React components.
+ */
+program
+    .command("build <src> <out>")
+    .description("Build all SVGs from source to output")
+    .action(async (src, out) => {
+    console.log("🛠️  Building SVGs...");
+    console.log("Source:", src);
+    console.log("Output:", out);
+    await buildAll({ src, out });
+});
+// -------- Watch Command --------
+/**
+ * Watch a source folder and rebuild SVGs automatically on changes.
+ *
+ * @param {string} src - Source folder to watch.
+ * @param {string} out - Output folder for generated components.
+ */
+program
+    .command("watch <src> <out>")
+    .description("Watch source folder and rebuild SVGs automatically")
+    .action((src, out) => {
+    console.log("🚀 Starting watch mode...");
+    watchSVGs({ src, out });
+});
+// -------- Generate Single SVG --------
+/**
+ * Generate a React component from a single SVG file.
+ *
+ * @param {string} svgFile - Path to the SVG file.
+ * @param {string} out - Output folder for the generated component.
+ */
+program
+    .command("generate <svgFile> <out>")
+    .description("Convert a single SVG file into a React component")
+    .action(async (svgFile, out) => {
+    await generateSVG({ svgFile, outDir: out });
+});
+// -------- Lock / Unlock --------
+/**
+ * Lock one or more SVG files to prevent accidental overwrites.
+ *
+ * @param {string[]} files - Paths to SVG files to lock.
+ */
+program
+    .command("lock <files...>")
+    .description("Lock one or more SVG files")
+    .action((files) => lockFiles(files));
+/**
+ * Unlock one or more SVG files to allow modifications.
+ *
+ * @param {string[]} files - Paths to SVG files to unlock.
+ */
+program
+    .command("unlock <files...>")
+    .description("Unlock one or more SVG files")
+    .action((files) => unlockFiles(files));
+// -------- Config --------
+/**
+ * Manage svger-cli configuration.
+ *
+ * Options:
+ * --init: Create default .svgconfig.json
+ * --set key=value: Set a configuration value
+ * --show: Show current configuration
+ *
+ * @param {Object} opts - CLI options
+ */
+program
+    .command("config")
+    .description("Manage svger-cli configuration")
+    .option("--init", "Create default .svgconfig.json")
+    .option("--set <keyValue>", "Set config key=value")
+    .option("--show", "Show current config")
+    .action((opts) => {
+    if (opts.init)
+        return initConfig();
+    if (opts.set) {
+        const [key, value] = opts.set.split("=");
+        if (!key || value === undefined) {
+            console.error("❌ Invalid format. Use key=value");
+            process.exit(1);
+        }
+        const parsedValue = !isNaN(Number(value)) ? Number(value) : value;
+        return setConfig(key, parsedValue);
+    }
+    if (opts.show)
+        return showConfig();
+    console.log("❌ No option provided. Use --init, --set, or --show");
+});
+// -------- Clean Command --------
+/**
+ * Remove all generated SVG React components from an output folder.
+ *
+ * @param {string} out - Output folder to clean.
+ */
+program
+    .command("clean <out>")
+    .description("Remove all generated SVG React components from output folder")
+    .action(async (out) => {
+    await clean(out);
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Read the current svger-cli configuration.
+ *
+ * @returns {Record<string, any>} Configuration object. Returns an empty object if no config file exists.
+ */
+export declare function readConfig(): Record<string, any>;
+/**
+ * Write a configuration object to the config file.
+ *
+ * @param {Record<string, any>} config - Configuration object to write.
+ */
+export declare function writeConfig(config: Record<string, any>): void;
+/**
+ * Initialize the svger-cli configuration with default values.
+ * If a config file already exists, this function will not overwrite it.
+ */
+export declare function initConfig(): void;
+/**
+ * Set a specific configuration key to a new value.
+ *
+ * @param {string} key - The config key to set.
+ * @param {any} value - The value to assign to the key.
+ */
+export declare function setConfig(key: string, value: any): void;
+/**
+ * Display the current configuration in the console.
+ */
+export declare function showConfig(): void;

package/dist/config.js

@@ -0,0 +1,74 @@
+import fs from "fs-extra";
+import path from "path";
+const CONFIG_FILE = ".svgconfig.json";
+/**
+ * Get the absolute path to the configuration file.
+ *
+ * @returns {string} Absolute path to .svgconfig.json
+ */
+function getConfigPath() {
+    return path.resolve(CONFIG_FILE);
+}
+/**
+ * Read the current svger-cli configuration.
+ *
+ * @returns {Record<string, any>} Configuration object. Returns an empty object if no config file exists.
+ */
+export function readConfig() {
+    if (!fs.existsSync(getConfigPath()))
+        return {};
+    return fs.readJSONSync(getConfigPath());
+}
+/**
+ * Write a configuration object to the config file.
+ *
+ * @param {Record<string, any>} config - Configuration object to write.
+ */
+export function writeConfig(config) {
+    fs.writeJSONSync(getConfigPath(), config, { spaces: 2 });
+}
+/**
+ * Initialize the svger-cli configuration with default values.
+ * If a config file already exists, this function will not overwrite it.
+ */
+export function initConfig() {
+    if (fs.existsSync(getConfigPath())) {
+        console.log("⚠️  Config file already exists:", getConfigPath());
+        return;
+    }
+    const defaultConfig = {
+        source: "./src/assets/svg",
+        output: "./src/components/icons",
+        watch: false,
+        defaultWidth: 24,
+        defaultHeight: 24,
+        defaultFill: "currentColor",
+        exclude: [],
+        styleRules: {
+            fill: "inherit",
+            stroke: "none",
+        },
+    };
+    writeConfig(defaultConfig);
+    console.log("✅ Config file created:", getConfigPath());
+}
+/**
+ * Set a specific configuration key to a new value.
+ *
+ * @param {string} key - The config key to set.
+ * @param {any} value - The value to assign to the key.
+ */
+export function setConfig(key, value) {
+    const config = readConfig();
+    config[key] = value;
+    writeConfig(config);
+    console.log(`✅ Set config ${key}=${value}`);
+}
+/**
+ * Display the current configuration in the console.
+ */
+export function showConfig() {
+    const config = readConfig();
+    console.log("📄 Current Config:");
+    console.log(JSON.stringify(config, null, 2));
+}

package/dist/lock.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lock one or more SVG files to prevent them from being processed.
+ *
+ * @param {string[]} files - Paths to SVG files to lock.
+ */
+export declare function lockFiles(files: string[]): void;
+/**
+ * Unlock one or more SVG files, allowing them to be processed again.
+ *
+ * @param {string[]} files - Paths to SVG files to unlock.
+ */
+export declare function unlockFiles(files: string[]): void;
+/**
+ * Check if a specific SVG file is locked.
+ *
+ * @param {string} file - Path to the SVG file to check.
+ * @returns {boolean} True if the file is locked, false otherwise.
+ */
+export declare function isLocked(file: string): boolean;

package/dist/lock.js

@@ -0,0 +1,69 @@
+import fs from "fs-extra";
+import path from "path";
+const LOCK_FILE = ".svg-lock";
+/**
+ * Get the absolute path to the lock file.
+ *
+ * @returns {string} Absolute path to .svg-lock
+ */
+function getLockFilePath() {
+    return path.resolve(LOCK_FILE);
+}
+/**
+ * Read the current locked SVG files from the lock file.
+ *
+ * @returns {string[]} Array of locked SVG file names.
+ */
+function readLockFile() {
+    if (!fs.existsSync(getLockFilePath()))
+        return [];
+    try {
+        const data = fs.readFileSync(getLockFilePath(), "utf-8");
+        return JSON.parse(data);
+    }
+    catch (e) {
+        return [];
+    }
+}
+/**
+ * Write the list of locked SVG files to the lock file.
+ *
+ * @param {string[]} files - Array of SVG file names to lock.
+ */
+function writeLockFile(files) {
+    fs.writeFileSync(getLockFilePath(), JSON.stringify(files, null, 2), "utf-8");
+}
+/**
+ * Lock one or more SVG files to prevent them from being processed.
+ *
+ * @param {string[]} files - Paths to SVG files to lock.
+ */
+export function lockFiles(files) {
+    const fileNames = files.map(f => path.basename(f));
+    const current = readLockFile();
+    const newFiles = Array.from(new Set([...current, ...fileNames]));
+    writeLockFile(newFiles);
+    console.log(`🔒 Locked files: ${newFiles.join(", ")}`);
+}
+/**
+ * Unlock one or more SVG files, allowing them to be processed again.
+ *
+ * @param {string[]} files - Paths to SVG files to unlock.
+ */
+export function unlockFiles(files) {
+    const fileNames = files.map(f => path.basename(f));
+    const current = readLockFile();
+    const remaining = current.filter(f => !fileNames.includes(f));
+    writeLockFile(remaining);
+    console.log(`🔓 Unlocked files: ${fileNames.join(", ")}`);
+}
+/**
+ * Check if a specific SVG file is locked.
+ *
+ * @param {string} file - Path to the SVG file to check.
+ * @returns {boolean} True if the file is locked, false otherwise.
+ */
+export function isLocked(file) {
+    const current = readLockFile();
+    return current.includes(path.basename(file));
+}

package/dist/templates/ComponentTemplate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generates a React functional component string from an SVG file's content.
+ *
+ * This template replaces XML/DOCTYPE declarations, cleans up formatting,
+ * and injects React props (`width`, `height`, `fill`, and any others via `...props`)
+ * directly into the root `<svg>` tag.
+ *
+ * @param {Object} params - Template generation parameters.
+ * @param {string} params.componentName - The name of the generated React component.
+ * @param {string} params.svgContent - The raw SVG markup to transform into a React component.
+ * @param {number} [params.defaultWidth=24] - Default width of the SVG (used if none is provided via props).
+ * @param {number} [params.defaultHeight=24] - Default height of the SVG (used if none is provided via props).
+ * @param {string} [params.defaultFill="currentColor"] - Default fill color of the SVG.
+ *
+ * @returns {string} The complete TypeScript React component code as a string.
+ *
+ * @example
+ * const svg = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>';
+ * const componentCode = reactTemplate({
+ *   componentName: "MyIcon",
+ *   svgContent: svg,
+ *   defaultWidth: 32,
+ *   defaultHeight: 32,
+ * });
+ *
+ * // Result: a ready-to-write .tsx file containing a typed React component
+ * console.log(componentCode);
+ */
+export declare function reactTemplate({ componentName, svgContent, defaultWidth, defaultHeight, defaultFill, }: {
+    componentName: string;
+    svgContent: string;
+    defaultWidth?: number;
+    defaultHeight?: number;
+    defaultFill?: string;
+}): string;

package/dist/templates/ComponentTemplate.js

@@ -0,0 +1,48 @@
+/**
+ * Generates a React functional component string from an SVG file's content.
+ *
+ * This template replaces XML/DOCTYPE declarations, cleans up formatting,
+ * and injects React props (`width`, `height`, `fill`, and any others via `...props`)
+ * directly into the root `<svg>` tag.
+ *
+ * @param {Object} params - Template generation parameters.
+ * @param {string} params.componentName - The name of the generated React component.
+ * @param {string} params.svgContent - The raw SVG markup to transform into a React component.
+ * @param {number} [params.defaultWidth=24] - Default width of the SVG (used if none is provided via props).
+ * @param {number} [params.defaultHeight=24] - Default height of the SVG (used if none is provided via props).
+ * @param {string} [params.defaultFill="currentColor"] - Default fill color of the SVG.
+ *
+ * @returns {string} The complete TypeScript React component code as a string.
+ *
+ * @example
+ * const svg = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>';
+ * const componentCode = reactTemplate({
+ *   componentName: "MyIcon",
+ *   svgContent: svg,
+ *   defaultWidth: 32,
+ *   defaultHeight: 32,
+ * });
+ *
+ * // Result: a ready-to-write .tsx file containing a typed React component
+ * console.log(componentCode);
+ */
+export function reactTemplate({ componentName, svgContent, defaultWidth = 24, defaultHeight = 24, defaultFill = "currentColor", }) {
+    const cleaned = svgContent
+        .replace(/<\?xml.*?\?>/g, "") // Remove XML declarations
+        .replace(/<!DOCTYPE.*?>/g, "") // Remove DOCTYPE lines
+        .replace(/\r?\n|\r/g, "") // Remove newlines
+        .trim();
+    return `import * as React from "react";
+
+export const ${componentName}: React.FC<React.SVGProps<SVGSVGElement>> = ({
+  width = ${defaultWidth},
+  height = ${defaultHeight},
+  fill = "${defaultFill}",
+  ...props
+}) => (
+  ${cleaned.replace(/<svg/, `<svg width={width} height={height} fill={fill} {...props}`)}
+);
+
+export default ${componentName};
+`;
+}