@tinloof/typed-svg-sprite 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @tinloof/typed-svg-sprite
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial release of @tinloof/typed-svg-sprite
+- Generate optimized SVG sprites with full TypeScript support
+- CLI tool for generating sprites from SVG files
+- Next.js integration with `withSpriteLoader`
+- Auto-generated TypeScript definitions
+- Auto-generated React Icon component
+- Watch mode for development

package/README.md

@@ -0,0 +1,190 @@
+# @tinloof/typed-svg-sprite
+
+> Generate optimized SVG sprites with full TypeScript support
+
+Automatically generates SVG sprite files with type-safe TypeScript definitions and a ready-to-use React component.
+
+## Installation
+
+```bash
+npm install @tinloof/typed-svg-sprite
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Generate sprite
+typed-svg-sprite --input public/icons --output public/sprite.svg
+
+# Watch mode
+typed-svg-sprite -i public/icons -o public/sprite.svg --watch
+```
+
+### Next.js
+
+```typescript
+// next.config.ts
+import { withSpriteLoader } from "@tinloof/typed-svg-sprite/next";
+
+export default withSpriteLoader({});
+```
+
+Place SVGs in `public/icons/` and use:
+
+```typescript
+import { HOME, SETTINGS } from "@/generated/icons";
+import { Icon } from "@/generated/Icon";
+
+function MyComponent() {
+  return (
+    <>
+      <Icon href={HOME} />
+      <Icon href={SETTINGS} size={32} />
+    </>
+  );
+}
+```
+
+## Usage
+
+### CLI Options
+
+```bash
+typed-svg-sprite --input <dir> --output <file> [options]
+
+Options:
+  -i, --input <dir>    Directory containing SVG files
+  -o, --output <file>  Output sprite file path
+  -w, --watch          Watch for changes and regenerate
+  -h, --help           Show help message
+```
+
+### Next.js Configuration
+
+```typescript
+export default withSpriteLoader(
+  {
+    // your existing Next.js config
+  },
+  {
+    inputDir?: string; // default: "public/icons"
+    outputFile?: string; // default: "public/sprite.svg"
+    url?: string; // default: "/"
+    filename?: string; // default: "sprite.svg"
+    typesOutputFile?: string; // default: "generated/icons.ts"
+    generateIconComponent?: boolean; // default: true
+    iconComponentOutputFile?: string; // default: "generated/Icon.tsx"
+  }
+);
+```
+
+## Generated Files
+
+### 1. Sprite (`public/sprite.svg`)
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" style="display:none">
+  <symbol id="a" viewBox="0 0 24 24"><!-- icon content --></symbol>
+  <symbol id="b" viewBox="0 0 24 24"><!-- icon content --></symbol>
+</svg>
+```
+
+### 2. TypeScript Types (`generated/icons.ts`)
+
+```typescript
+export enum IconId {
+  HOME = "a",
+  SETTINGS = "b",
+}
+
+export type IconHref = `/sprite.svg#${IconId}`;
+
+export const HOME: IconHref = "/sprite.svg#a";
+export const SETTINGS: IconHref = "/sprite.svg#b";
+
+export function getIconHref(iconId: IconId): IconHref;
+export const allIcons: IconId[];
+```
+
+### 3. React Component (`generated/Icon.tsx`)
+
+```typescript
+import { IconHref } from "./icons";
+
+export interface IconProps extends React.SVGProps<SVGSVGElement> {
+  href: IconHref;
+  size?: number | string;
+}
+
+export function Icon({ href, size = 24, ...props }: IconProps) {
+  // ...
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { HOME, SEARCH, SETTINGS } from "@/generated/icons";
+import { Icon } from "@/generated/Icon";
+
+<Icon href={HOME} />
+<Icon href={SEARCH} size={20} />
+<Icon href={SETTINGS} className="text-blue-500" />
+```
+
+### Dynamic Icons
+
+```typescript
+import { IconId, getIconHref } from "@/generated/icons";
+
+function DynamicIcon({ iconId }: { iconId: IconId }) {
+  return <Icon href={getIconHref(iconId)} />;
+}
+```
+
+### Build Script Integration
+
+```json
+{
+  "scripts": {
+    "generate:icons": "typed-svg-sprite --input public/icons --output public/sprite.svg",
+    "build": "npm run generate:icons && next build"
+  }
+}
+```
+
+### Without React
+
+```bash
+# Generate sprite and types
+typed-svg-sprite --input src/icons --output public/sprite.svg
+
+# Use generated types
+import { HOME, SETTINGS } from "./generated/icons";
+
+// In your HTML/JS
+<svg><use href={HOME} /></svg>
+```
+
+## How It Works
+
+1. Scans directory for `.svg` files
+2. Extracts and optimizes SVG content
+3. Generates compact base-52 IDs (`a`, `b`, `aa`, etc.)
+4. Combines into single sprite file
+5. Generates TypeScript types with file-based names
+6. Generates React component (optional)
+
+**Symbol IDs**: Short IDs (`a`, `b`) in sprite, original names (`HOME`, `SETTINGS`) in TypeScript exports.
+
+## Roadmap
+
+- [ ] Integrate SVGO for advanced SVG optimization
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const core_js_1 = require("./core.js");
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--input":
+            case "-i":
+                options.input = args[++i];
+                break;
+            case "--output":
+            case "-o":
+                options.output = args[++i];
+                break;
+            case "--watch":
+            case "-w":
+                options.watch = true;
+                break;
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+        }
+    }
+    if (!options.input || !options.output) {
+        console.error("Error: --input and --output are required\n");
+        printHelp();
+        process.exit(1);
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`
+SVG Sprite Generator
+
+Usage:
+  typed-svg-sprite --input <dir> --output <file> [options]
+
+Options:
+  -i, --input <dir>    Directory containing SVG files
+  -o, --output <file>  Output sprite file path
+  -w, --watch          Watch for changes and regenerate
+  -h, --help           Show this help message
+
+Examples:
+  typed-svg-sprite --input public/icons --output public/sprite.svg
+  typed-svg-sprite -i ./icons -o ./dist/sprite.svg --watch
+`);
+}
+function runSpriteGeneration(inputDir, outputFile) {
+    try {
+        (0, core_js_1.generateSprite)({
+            inputDir,
+            outputFile,
+            verbose: true,
+            minify: true,
+        });
+    }
+    catch (error) {
+        console.error("Error generating sprite:", error);
+        process.exit(1);
+    }
+}
+function main() {
+    const options = parseArgs();
+    // Initial generation
+    runSpriteGeneration(options.input, options.output);
+    // Watch mode
+    if (options.watch) {
+        const absoluteInputDir = path.resolve(process.cwd(), options.input);
+        console.log(`\n👀 Watching ${options.input} for changes...`);
+        fs.watch(absoluteInputDir, { recursive: true }, (_eventType, filename) => {
+            if (filename?.endsWith(".svg")) {
+                console.log(`\n📝 Change detected: ${filename}`);
+                runSpriteGeneration(options.input, options.output);
+            }
+        });
+    }
+}
+main();

package/dist/components.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for Icon component generation
+ */
+export interface IconComponentGenerationOptions {
+    /**
+     * Output path for the Icon component file
+     * Can be relative or absolute path
+     */
+    outputFile: string;
+    /**
+     * Path to the generated types file (for import statement)
+     * Relative to the component output file
+     */
+    typesFileRelativePath: string;
+    /**
+     * Whether to log output messages
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Generate React Icon component file
+ */
+export declare function generateIconComponent(options: IconComponentGenerationOptions): void;

package/dist/components.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateIconComponent = generateIconComponent;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Generate React Icon component file
+ */
+function generateIconComponent(options) {
+    const { outputFile, typesFileRelativePath, verbose = true } = options;
+    try {
+        const projectRoot = process.cwd();
+        const absoluteOutputFile = path.resolve(projectRoot, outputFile);
+        // Normalize the import path (ensure it uses / separator and doesn't start with ./ if in same dir)
+        const normalizedImportPath = typesFileRelativePath
+            .replace(/\\/g, "/")
+            .replace(/\.tsx?$/, "");
+        const content = `// Auto-generated by typed-svg-sprite
+// Do not edit this file manually
+
+import { IconHref } from "${normalizedImportPath}";
+
+export interface IconProps extends React.SVGProps<SVGSVGElement> {
+  /** The icon href (import from generated/icons.ts) */
+  href: IconHref;
+  /** Size shorthand for width and height */
+  size?: number | string;
+}
+
+export function Icon({
+  href,
+  size = 24,
+  width,
+  height,
+  className = "",
+  viewBox = "0 0 24 24",
+  fill = "currentColor",
+  ...props
+}: IconProps) {
+  return (
+    <svg
+      className={className}
+      width={width || size}
+      height={height || size}
+      viewBox={viewBox}
+      fill={fill}
+      aria-hidden="true"
+      {...props}
+    >
+      <use href={href} />
+    </svg>
+  );
+}
+`;
+        // Write component file
+        const outputDir = path.dirname(absoluteOutputFile);
+        fs.mkdirSync(outputDir, { recursive: true });
+        fs.writeFileSync(absoluteOutputFile, content, "utf8");
+        if (verbose) {
+            console.log(`[svg-sprite] ✅ Generated Icon component → ${outputFile}`);
+        }
+    }
+    catch (error) {
+        if (verbose) {
+            console.error("[svg-sprite] Error generating Icon component:", error);
+        }
+        throw error;
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Represents an SVG symbol with its metadata
+ */
+export interface SvgSymbol {
+    id: string;
+    originalId: string;
+    viewBox: string;
+    content: string;
+    attributes: Record<string, string>;
+}
+/**
+ * Options for sprite generation
+ */
+export interface SpriteGenerationOptions {
+    /**
+     * Directory containing SVG files to include in the sprite.
+     * Can be relative or absolute path.
+     */
+    inputDir: string;
+    /**
+     * Output path for the sprite file.
+     * Can be relative or absolute path.
+     */
+    outputFile: string;
+    /**
+     * Whether to log output messages
+     * @default true
+     */
+    verbose?: boolean;
+    /**
+     * Whether to minify the output
+     * @default true
+     */
+    minify?: boolean;
+    /**
+     * Whether to optimize/compress the SVG content
+     * @default true
+     */
+    optimize?: boolean;
+}
+/**
+ * Generate a symbol ID from a file path relative to a base directory.
+ * Converts the path to kebab-case and sanitizes it.
+ *
+ * @example
+ * generateSymbolIdFromPath("/path/to/icons/social/github.svg", "/path/to/icons")
+ * // Returns: "social-github"
+ */
+export declare function generateSymbolIdFromPath(filePath: string, baseDir: string): string;
+/**
+ * Parse an SVG file and extract its symbol data
+ */
+export declare function parseSvgFile(svgContent: string, originalId: string, shortId: string, shouldOptimize?: boolean): SvgSymbol;
+/**
+ * Generate the SVG sprite content from symbols
+ */
+export declare function generateSpriteSvg(symbols: SvgSymbol[], minify?: boolean): string;
+/**
+ * Find and parse all SVG files in a directory
+ */
+export declare function findAndParseSvgFiles(inputDir: string, verbose?: boolean, optimize?: boolean): SvgSymbol[];
+/**
+ * Generate an SVG sprite file from a directory of SVG files
+ */
+export declare function generateSprite(options: SpriteGenerationOptions): SvgSymbol[];

package/dist/core.js

@@ -0,0 +1,245 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSymbolIdFromPath = generateSymbolIdFromPath;
+exports.parseSvgFile = parseSvgFile;
+exports.generateSpriteSvg = generateSpriteSvg;
+exports.findAndParseSvgFiles = findAndParseSvgFiles;
+exports.generateSprite = generateSprite;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const cheerio = __importStar(require("cheerio"));
+const glob_1 = require("glob");
+/**
+ * Generate a symbol ID from a file path relative to a base directory.
+ * Converts the path to kebab-case and sanitizes it.
+ *
+ * @example
+ * generateSymbolIdFromPath("/path/to/icons/social/github.svg", "/path/to/icons")
+ * // Returns: "social-github"
+ */
+function generateSymbolIdFromPath(filePath, baseDir) {
+    const relativePath = path.relative(baseDir, filePath);
+    const pathWithoutExt = relativePath.replace(/\.svg$/, "");
+    const symbolId = pathWithoutExt
+        .replace(/[\/\\]/g, "-")
+        .replace(/[^a-zA-Z0-9-_]/g, "-")
+        .replace(/--+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return symbolId;
+}
+/**
+ * Generate a short, unique ID for a symbol
+ * Uses base-52 encoding (a-z, A-Z) for compact IDs
+ */
+function generateShortId(index) {
+    const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    const maxIndex = chars.length;
+    let id = "";
+    let num = index;
+    do {
+        id = chars[num % maxIndex] + id;
+        num = Math.floor(num / maxIndex);
+    } while (num > 0);
+    return id;
+}
+/**
+ * Optimize SVG content by removing unnecessary whitespace and simplifying values
+ */
+function optimizeSvgContent(content) {
+    return (content
+        // Remove comments
+        .replace(/<!--[\s\S]*?-->/g, "")
+        // Remove unnecessary whitespace between tags
+        .replace(/>\s+</g, "><")
+        // Simplify numbers: remove trailing zeros after decimal
+        .replace(/(\d+\.\d*?)0+(?=\D)/g, "$1")
+        // Remove unnecessary decimal points (1.0 -> 1)
+        .replace(/(\d+)\.0+(?=\D)/g, "$1")
+        // Compress multiple spaces to single space
+        .replace(/\s+/g, " ")
+        // Remove spaces around equals signs in attributes
+        .replace(/\s*=\s*/g, "=")
+        // Remove leading/trailing whitespace
+        .trim());
+}
+/**
+ * Parse an SVG file and extract its symbol data
+ */
+function parseSvgFile(svgContent, originalId, shortId, shouldOptimize = true) {
+    // Optimize content if requested
+    const processedContent = shouldOptimize
+        ? optimizeSvgContent(svgContent)
+        : svgContent;
+    const $ = cheerio.load(processedContent, { xmlMode: true });
+    const $svg = $("svg").first();
+    if ($svg.length === 0) {
+        throw new Error("Invalid SVG content");
+    }
+    let viewBox = $svg.attr("viewBox");
+    if (!viewBox) {
+        const width = $svg.attr("width") || "24";
+        const height = $svg.attr("height") || "24";
+        viewBox = `0 0 ${width} ${height}`;
+    }
+    const attributes = {};
+    const svgAttribs = $svg.get(0)?.attribs || {};
+    const excludeAttribs = new Set([
+        "viewBox",
+        "width",
+        "height",
+        "xmlns",
+        "xmlns:xlink",
+    ]);
+    for (const [key, value] of Object.entries(svgAttribs)) {
+        if (!excludeAttribs.has(key) && value) {
+            attributes[key] = value;
+        }
+    }
+    return {
+        id: shortId,
+        originalId: originalId,
+        viewBox: viewBox,
+        content: $svg.html() || "",
+        attributes: attributes,
+    };
+}
+/**
+ * Generate the SVG sprite content from symbols
+ */
+function generateSpriteSvg(symbols, minify = true) {
+    if (symbols.length === 0) {
+        return minify
+            ? '<svg xmlns="http://www.w3.org/2000/svg" style="display:none"></svg>'
+            : `<svg xmlns="http://www.w3.org/2000/svg" class="svg-sprite" style="display: none;">
+</svg>`;
+    }
+    const symbolElements = symbols
+        .map((symbol) => {
+        let attributesStr = "";
+        for (const [key, value] of Object.entries(symbol.attributes)) {
+            attributesStr += ` ${key}="${value}"`;
+        }
+        return `<symbol id="${symbol.id}" viewBox="${symbol.viewBox}"${attributesStr}>${symbol.content}</symbol>`;
+    })
+        .join(minify ? "" : "\n  ");
+    if (minify) {
+        return `<svg xmlns="http://www.w3.org/2000/svg" style="display:none">${symbolElements}</svg>`;
+    }
+    return `<svg xmlns="http://www.w3.org/2000/svg" class="svg-sprite" style="display: none;">
+  ${symbolElements}
+</svg>`;
+}
+/**
+ * Find and parse all SVG files in a directory
+ */
+function findAndParseSvgFiles(inputDir, verbose = true, optimize = true) {
+    const absoluteInputDir = path.resolve(process.cwd(), inputDir);
+    // Check if input directory exists
+    if (!fs.existsSync(absoluteInputDir)) {
+        if (verbose) {
+            console.warn(`Input directory not found: ${inputDir}`);
+        }
+        return [];
+    }
+    // Find all SVG files
+    const svgFiles = (0, glob_1.globSync)("**/*.svg", {
+        cwd: absoluteInputDir,
+        absolute: true,
+    });
+    if (svgFiles.length === 0) {
+        if (verbose) {
+            console.warn(`No SVG files found in ${inputDir}`);
+        }
+        return [];
+    }
+    if (verbose) {
+        console.log(`Found ${svgFiles.length} SVG files in ${inputDir}`);
+    }
+    // Parse all SVG files
+    const symbols = [];
+    for (let i = 0; i < svgFiles.length; i++) {
+        const svgFile = svgFiles[i];
+        try {
+            const content = fs.readFileSync(svgFile, "utf8");
+            const originalId = generateSymbolIdFromPath(svgFile, absoluteInputDir);
+            const shortId = generateShortId(i);
+            const symbol = parseSvgFile(content, originalId, shortId, optimize);
+            symbols.push(symbol);
+        }
+        catch (error) {
+            if (verbose) {
+                console.error(`Error parsing ${svgFile}:`, error);
+            }
+        }
+    }
+    return symbols;
+}
+/**
+ * Generate an SVG sprite file from a directory of SVG files
+ */
+function generateSprite(options) {
+    const { inputDir, outputFile, verbose = true, minify = true, optimize = true, } = options;
+    try {
+        const projectRoot = process.cwd();
+        const absoluteOutputFile = path.resolve(projectRoot, outputFile);
+        // Find and parse SVG files
+        const symbols = findAndParseSvgFiles(inputDir, verbose, optimize);
+        if (symbols.length === 0) {
+            return symbols;
+        }
+        // Generate sprite
+        let spriteContent = generateSpriteSvg(symbols, minify);
+        // Additional optimization on final sprite
+        if (optimize) {
+            spriteContent = optimizeSvgContent(spriteContent);
+        }
+        // Write sprite file
+        const outputDir = path.dirname(absoluteOutputFile);
+        fs.mkdirSync(outputDir, { recursive: true });
+        fs.writeFileSync(absoluteOutputFile, spriteContent, "utf8");
+        if (verbose) {
+            const sizeKB = (Buffer.byteLength(spriteContent, "utf8") / 1024).toFixed(2);
+            console.log(`✅ Generated sprite with ${symbols.length} symbols (${sizeKB} KB) → ${outputFile}`);
+        }
+        return symbols;
+    }
+    catch (error) {
+        if (verbose) {
+            console.error("Error generating sprite:", error);
+        }
+        throw error;
+    }
+}

package/dist/next.d.ts

@@ -0,0 +1,111 @@
+interface NextConfig {
+    [key: string]: any;
+}
+interface SpriteLoaderOptions {
+    /**
+     * URL path where the sprite file will be served from.
+     * @default "/"
+     */
+    url?: string;
+    /**
+     * Filename for the sprite file.
+     * @default "sprite.svg"
+     */
+    filename?: string;
+    /**
+     * Directory containing SVG files to include in the sprite.
+     * Relative to project root.
+     * @default "public/icons"
+     */
+    inputDir?: string;
+    /**
+     * Output path for the sprite file.
+     * Relative to project root.
+     * @default "public/sprite.svg"
+     */
+    outputFile?: string;
+    /**
+     * Output path for the TypeScript types file.
+     * Relative to project root.
+     * @default "generated/icons.ts"
+     */
+    typesOutputFile?: string;
+    /**
+     * Whether to generate the Icon React component.
+     * @default true
+     */
+    generateIconComponent?: boolean;
+    /**
+     * Output path for the Icon component file.
+     * Relative to project root.
+     * @default "generated/Icon.tsx"
+     */
+    iconComponentOutputFile?: string;
+}
+/**
+ * Generates SVG sprite and TypeScript types for Next.js projects
+ *
+ * This function generates:
+ * 1. An SVG sprite file containing all icons
+ * 2. A TypeScript file with typed icon IDs and helper functions
+ *
+ * No loader is needed - just import the typed icon references directly.
+ *
+ * @param nextConfig - The existing Next.js configuration object
+ * @param options - Optional sprite generation configuration
+ * @returns Next.js configuration (unchanged, sprite generation happens during config)
+ *
+ * @example
+ * ```typescript
+ * // next.config.ts
+ * import { withSpriteLoader } from '@tinloof/typed-svg-sprite/next';
+ *
+ * export default withSpriteLoader({
+ *   // your existing Next.js config
+ * });
+ *
+ * // Then in your components:
+ * import { HOME, SETTINGS } from '@/generated/icons';
+ * import { Icon } from '@/generated/Icon'; // Icon component is auto-generated
+ *
+ * function MyComponent() {
+ *   return (
+ *     <>
+ *       <Icon href={HOME} />
+ *       <Icon href={SETTINGS} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * export default withSpriteLoader(
+ *   {
+ *     // your existing Next.js config
+ *   },
+ *   {
+ *     inputDir: "assets/icons",
+ *     outputFile: "public/icons-sprite.svg",
+ *     typesOutputFile: "lib/icons.ts",
+ *     iconComponentOutputFile: "components/Icon.tsx",
+ *     url: "/",
+ *     filename: "icons-sprite.svg"
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable Icon component generation
+ * export default withSpriteLoader(
+ *   { /* your config *\/ },
+ *   {
+ *     generateIconComponent: false
+ *   }
+ * );
+ * ```
+ */
+export declare function withSpriteLoader(nextConfig: any, options?: SpriteLoaderOptions): NextConfig;
+export {};

package/dist/next.js

@@ -0,0 +1,202 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSpriteLoader = withSpriteLoader;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const core_js_1 = require("./core.js");
+const types_js_1 = require("./types.js");
+const components_js_1 = require("./components.js");
+// Track if we've already started watching
+let watcherInitialized = false;
+function generateSpriteAndTypes(inputDir, outputFile, spriteUrl, spriteFilename, typesOutputFile, generateIcon, iconComponentOutputFile) {
+    // Generate sprite and get symbols
+    const symbols = (0, core_js_1.generateSprite)({
+        inputDir,
+        outputFile,
+        verbose: true,
+        minify: true,
+        optimize: true,
+    });
+    // Generate TypeScript types file if specified
+    if (typesOutputFile && symbols.length > 0) {
+        (0, types_js_1.generateTypesFile)({
+            symbols,
+            spriteUrl,
+            spriteFilename,
+            outputFile: typesOutputFile,
+            verbose: false,
+        });
+        // Generate Icon component if enabled
+        if (generateIcon && iconComponentOutputFile) {
+            // Calculate relative path from component to types file
+            const componentDir = path.dirname(path.resolve(process.cwd(), iconComponentOutputFile));
+            const typesFile = path.resolve(process.cwd(), typesOutputFile);
+            const typesDir = path.dirname(typesFile);
+            const typesFilename = path.basename(typesFile, path.extname(typesFile));
+            // Get relative path from component dir to types dir
+            const relativePath = path
+                .relative(componentDir, typesDir)
+                .replace(/\\/g, "/");
+            // Construct the import path
+            // If same directory, use ./filename
+            // If parent/child relationship, ensure proper path format
+            let importPath;
+            if (relativePath === "") {
+                importPath = `./${typesFilename}`;
+            }
+            else if (relativePath.startsWith("..")) {
+                // Parent directory - ensure proper path
+                importPath = `${relativePath}/${typesFilename}`.replace(/\/+/g, "/");
+            }
+            else {
+                // Child directory - ensure it starts with ./
+                const normalizedPath = relativePath.startsWith("./")
+                    ? relativePath
+                    : `./${relativePath}`;
+                importPath = `${normalizedPath}/${typesFilename}`.replace(/\/+/g, "/");
+            }
+            (0, components_js_1.generateIconComponent)({
+                outputFile: iconComponentOutputFile,
+                typesFileRelativePath: importPath,
+                verbose: false,
+            });
+        }
+    }
+}
+function startWatcher(inputDir, outputFile, spriteUrl, spriteFilename, typesOutputFile, generateIcon, iconComponentOutputFile) {
+    if (watcherInitialized) {
+        return;
+    }
+    const projectRoot = process.cwd();
+    const absoluteInputDir = path.resolve(projectRoot, inputDir);
+    if (!fs.existsSync(absoluteInputDir)) {
+        return;
+    }
+    watcherInitialized = true;
+    console.log(`[svg-sprite] 👀 Watching ${inputDir} for changes...`);
+    fs.watch(absoluteInputDir, { recursive: true }, (eventType, filename) => {
+        if (filename?.endsWith(".svg")) {
+            console.log(`[svg-sprite] Change detected: ${filename}`);
+            generateSpriteAndTypes(inputDir, outputFile, spriteUrl, spriteFilename, typesOutputFile, generateIcon, iconComponentOutputFile);
+        }
+    });
+}
+/**
+ * Generates SVG sprite and TypeScript types for Next.js projects
+ *
+ * This function generates:
+ * 1. An SVG sprite file containing all icons
+ * 2. A TypeScript file with typed icon IDs and helper functions
+ *
+ * No loader is needed - just import the typed icon references directly.
+ *
+ * @param nextConfig - The existing Next.js configuration object
+ * @param options - Optional sprite generation configuration
+ * @returns Next.js configuration (unchanged, sprite generation happens during config)
+ *
+ * @example
+ * ```typescript
+ * // next.config.ts
+ * import { withSpriteLoader } from '@tinloof/typed-svg-sprite/next';
+ *
+ * export default withSpriteLoader({
+ *   // your existing Next.js config
+ * });
+ *
+ * // Then in your components:
+ * import { HOME, SETTINGS } from '@/generated/icons';
+ * import { Icon } from '@/generated/Icon'; // Icon component is auto-generated
+ *
+ * function MyComponent() {
+ *   return (
+ *     <>
+ *       <Icon href={HOME} />
+ *       <Icon href={SETTINGS} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * export default withSpriteLoader(
+ *   {
+ *     // your existing Next.js config
+ *   },
+ *   {
+ *     inputDir: "assets/icons",
+ *     outputFile: "public/icons-sprite.svg",
+ *     typesOutputFile: "lib/icons.ts",
+ *     iconComponentOutputFile: "components/Icon.tsx",
+ *     url: "/",
+ *     filename: "icons-sprite.svg"
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable Icon component generation
+ * export default withSpriteLoader(
+ *   { /* your config *\/ },
+ *   {
+ *     generateIconComponent: false
+ *   }
+ * );
+ * ```
+ */
+function withSpriteLoader(nextConfig, options) {
+    const inputDir = options?.inputDir ?? "public/icons";
+    const outputFile = options?.outputFile ?? "public/sprite.svg";
+    const spriteUrl = options?.url ?? "/";
+    const spriteFilename = options?.filename ?? "sprite.svg";
+    const typesOutputFile = options?.typesOutputFile ?? "generated/icons.ts";
+    const generateIcon = options?.generateIconComponent !== false
+        ? options?.generateIconComponent ?? true
+        : false;
+    const iconComponentOutputFile = options?.iconComponentOutputFile ?? "generated/Icon.tsx";
+    // Generate sprite and types on startup
+    generateSpriteAndTypes(inputDir, outputFile, spriteUrl, spriteFilename, typesOutputFile, generateIcon, generateIcon ? iconComponentOutputFile : undefined);
+    // Start watcher in dev mode
+    const isDev = process.env.NODE_ENV === "development";
+    if (isDev) {
+        startWatcher(inputDir, outputFile, spriteUrl, spriteFilename, typesOutputFile, generateIcon, generateIcon ? iconComponentOutputFile : undefined);
+    }
+    // Return config without loader modifications
+    // Users should import from the generated types file instead
+    return nextConfig;
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+import type { SvgSymbol } from "./core.js";
+/**
+ * Options for TypeScript types generation
+ */
+export interface TypesGenerationOptions {
+    /**
+     * Symbols to generate types for
+     */
+    symbols: SvgSymbol[];
+    /**
+     * URL path where the sprite file will be served from
+     * @example "/"
+     */
+    spriteUrl: string;
+    /**
+     * Filename of the sprite file
+     * @example "sprite.svg"
+     */
+    spriteFilename: string;
+    /**
+     * Output path for the TypeScript types file
+     * Can be relative or absolute path
+     */
+    outputFile: string;
+    /**
+     * Whether to log output messages
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Generate TypeScript types file from SVG symbols
+ */
+export declare function generateTypesFile(options: TypesGenerationOptions): void;

package/dist/types.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTypesFile = generateTypesFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Generate TypeScript types file from SVG symbols
+ */
+function generateTypesFile(options) {
+    const { symbols, spriteUrl, spriteFilename, outputFile, verbose = true, } = options;
+    try {
+        const projectRoot = process.cwd();
+        const absoluteOutputFile = path.resolve(projectRoot, outputFile);
+        const spriteUrlWithFilename = spriteUrl.endsWith("/")
+            ? `${spriteUrl}${spriteFilename}`
+            : `${spriteUrl}/${spriteFilename}`;
+        // Generate TypeScript content
+        const enumEntries = symbols
+            .map((s) => {
+            // Convert kebab-case to UPPER_SNAKE_CASE for enum key (use originalId)
+            const enumKey = s.originalId.replace(/-/g, "_").toUpperCase();
+            // But reference the short ID in the value
+            return `  ${enumKey} = "${s.id}",`;
+        })
+            .join("\n");
+        const iconExports = symbols
+            .map((s) => {
+            const constantName = s.originalId.replace(/-/g, "_").toUpperCase();
+            return `export const ${constantName}: IconHref = "${spriteUrlWithFilename}#${s.id}";`;
+        })
+            .join("\n");
+        const content = `// Auto-generated by typed-svg-sprite
+// Do not edit this file manually
+
+/**
+ * Available icon IDs in the sprite
+ */
+export enum IconId {
+${enumEntries}
+}
+
+/**
+ * Type-safe icon href (sprite URL + fragment identifier)
+ */
+export type IconHref = \`${spriteUrlWithFilename}#\${IconId}\`;
+
+/**
+ * Get the full sprite URL for an icon ID
+ */
+export function getIconHref(iconId: IconId): IconHref {
+  return \`${spriteUrlWithFilename}#\${iconId}\` as IconHref;
+}
+
+/**
+ * Pre-built icon references
+ */
+${iconExports}
+
+/**
+ * All available icons as an array
+ */
+export const allIcons: IconId[] = [
+${symbols
+            .map((s) => `  IconId.${s.originalId.replace(/-/g, "_").toUpperCase()},`)
+            .join("\n")}
+];
+`;
+        // Write types file
+        const outputDir = path.dirname(absoluteOutputFile);
+        fs.mkdirSync(outputDir, { recursive: true });
+        fs.writeFileSync(absoluteOutputFile, content, "utf8");
+        if (verbose) {
+            console.log(`[svg-sprite] ✅ Generated types file → ${outputFile}`);
+        }
+    }
+    catch (error) {
+        if (verbose) {
+            console.error("[svg-sprite] Error generating types file:", error);
+        }
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tinloof/typed-svg-sprite",
+  "version": "0.0.1",
+  "description": "Generate optimized SVG sprites with full TypeScript support",
+  "bin": {
+    "typed-svg-sprite": "./dist/cli.js"
+  },
+  "exports": {
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "clean": "rimraf dist",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "svg",
+    "sprite",
+    "icon",
+    "typescript",
+    "nextjs",
+    "cli"
+  ],
+  "author": "LHDi <elhadi98@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tinloof/typed-svg-sprite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tinloof/typed-svg-sprite/issues"
+  },
+  "homepage": "https://github.com/tinloof/typed-svg-sprite#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "cheerio": "^1.1.2",
+    "glob": "^10.3.10"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/cheerio": "^0.22.35",
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.0.0"
+  }
+}