svger-cli 2.0.7 → 3.0.0

package/README.md

@@ -1,13 +1,14 @@
-# SVGER-CLI v2.0.7 - Enterprise SVG Processing Framework
+# SVGER-CLI v3.0.0 - Enterprise SVG Processing Framework
 
 [![npm version](https://badge.fury.io/js/svger-cli.svg)](https://badge.fury.io/js/svger-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-green.svg)](https://www.npmjs.com/package/svger-cli)
 
-> **The most advanced, zero-dependency SVG to component converter, now with first-class support for
-> 9+ UI frameworks including React Native. Enjoy enterprise-grade performance, auto-generated
-> exports, and a unified workflow for your entire design system.**
+> **The most advanced, zero-dependency SVG to component converter with official build tool
+> integrations. First-class support for Webpack, Vite, Rollup, Babel, Next.js, and Jest. Supporting
+> 9+ UI frameworks including React Native with enterprise-grade performance and auto-generated
+> exports.**
 
 ---
 
@@ -16,7 +17,14 @@
 ### 🚀 **Getting Started**
 
 - [📦 Installation](#-installation)
-- [🚀 Quick Start: Your First Conversion](#-quick-start-your-first-conversion)
+- [� Build Tool Integrations](#-build-tool-integrations) **← NEW in v3.0**
+  - [Webpack](#webpack-integration)
+  - [Vite](#vite-integration)
+  - [Rollup](#rollup-integration)
+  - [Babel](#babel-integration)
+  - [Next.js](#nextjs-integration)
+  - [Jest](#jest-integration)
+- [�🚀 Quick Start: Your First Conversion](#-quick-start-your-first-conversion)
 - [💡 Why SVGER-CLI?](#-why-svger-cli-the-zero-dependency-advantage)
 
 ### 📚 **Core Documentation**
@@ -74,6 +82,32 @@
 | ------------------------------------- | --------------------------------------------------------------- |
 | 🎯 Get started immediately            | [Quick Start](#-quick-start-your-first-conversion)              |
 | 📦 Install the package                | [Installation](#-installation)                                  |
+| 🔧 Use with Webpack/Vite/Rollup       | [Build Tool Integrations](#-build-tool-integrations) **NEW**    |
+| ⚙️ Configure Webpack                  | [Webpack Integration](#webpack-integration)                     |
+| ⚡ Set up Vite                        | [Vite Integration](#vite-integration)                           |
+| 📦 Use with Rollup                    | [Rollup Integration](#rollup-integration)                       |
+| 🔄 Integrate Babel                    | [Babel Integration](#babel-integration)                         |
+| ▲ Use with Next.js                    | [Next.js Integration](#nextjs-integration)                      |
+| 🧪 Set up Jest                        | [Jest Integration](#jest-integration)                           |
+| 🤔 Understand why SVGER-CLI is better | [Why SVGER-CLI?](#-why-svger-cli-the-zero-dependency-advantage) |
+| ⚡ Compare features with competitors  | [Feature Comparison](#-feature-comparison-matrix)               |
+| 🚀 Convert SVGs to React components   | [React Guide](#react)                                           |
+| 📱 Use with React Native              | [React Native Guide](#react-native)                             |
+| 💚 Use with Vue                       | [Vue Guide](#vue-3)                                             |
+| 🅰️ Use with Angular                   | [Angular Guide](#angular)                                       |
+| 🌪️ Use with Svelte                    | [Svelte Guide](#svelte)                                         |
+| 📖 Learn all CLI commands             | [CLI Reference](#-comprehensive-cli-reference)                  |
+| 💻 Use the programmatic API           | [API Reference](#-programmatic-api)                             |
+| 🎨 Configure styling & theming        | [Styling Guide](#-advanced-styling--theming)                    |
+| ⚡ Optimize performance               | [Performance Guide](#-performance-optimization)                 |
+| 🚀 Deploy to production               | [Deployment Guide](#-production-deployment)                     |
+| 🐳 Use with Docker                    | [Docker Setup](#docker-integration)                             |
+| 🧪 Test my components                 | [Testing Guide](#-testing--quality-assurance)                   |
+| 🔧 Configure everything               | [Configuration Reference](#-configuration-reference)            |
+| 🔌 Create custom plugins              | [Plugin Development](#-plugin-development)                      |
+| 🐛 Fix issues                         | [Troubleshooting](#-troubleshooting--faq)                       |
+| 📚 Migrate from another tool          | [Migration Guide](#-migration-guide)                            |
+| 📦 Install the package                | [Installation](#-installation)                                  |
 | 🤔 Understand why SVGER-CLI is better | [Why SVGER-CLI?](#-why-svger-cli-the-zero-dependency-advantage) |
 | ⚡ Compare features with competitors  | [Feature Comparison](#-feature-comparison-matrix)               |
 | 🚀 Convert SVGs to React components   | [React Guide](#react)                                           |
@@ -99,10 +133,34 @@
 
 ## 🌟 **Key Features Overview**
 
+### **🔧 Official Build Tool Integrations (NEW in v3.0)**
+
+First-class support for all major build tools with zero configuration:
+
+- ✅ **Webpack Plugin** - HMR, watch mode, and loader support
+- ✅ **Vite Plugin** - Lightning-fast HMR and virtual modules
+- ✅ **Rollup Plugin** - Tree-shaking and source maps
+- ✅ **Babel Plugin** - Universal transpilation and import transformation
+- ✅ **Next.js Integration** - SSR support for App and Pages Router
+- ✅ **Jest Preset** - SVG transformers and mocking for tests
+
+```javascript
+// One-line setup for any build tool
+const { SvgerWebpackPlugin } = require('svger-cli/webpack');
+import { svgerVitePlugin } from 'svger-cli/vite';
+import { svgerRollupPlugin } from 'svger-cli/rollup';
+const { svgerBabelPlugin } = require('svger-cli/babel');
+const { withSvger } = require('svger-cli/nextjs');
+```
+
+**[See full integration guide →](#-build-tool-integrations)**
+
+---
+
 ### **✨ Auto-Generated index.ts Exports (Enhanced)**
 
-Automatically generates clean index.ts files with **unified export pattern** for maximum
-flexibility:
+Automatically generates clean index.ts files with a **single, consistent export pattern** that
+avoids naming conflicts:
 
 ```typescript
 // Auto-generated in your output directory
@@ -110,11 +168,16 @@ flexibility:
 export { default as ArrowLeft } from './ArrowLeft';
 export { default as ArrowRight } from './ArrowRight';
 
-// Grouped named exports
-export { ArrowLeft, ArrowRight };
-
-// Default export for convenience
-export default { ArrowLeft, ArrowRight };
+/**
+ * SVG Components Index
+ * Generated by svger-cli
+ *
+ * Import individual components:
+ * import { ArrowLeft } from './components';
+ *
+ * Import all components:
+ * import * as Icons from './components';
+ */
 ```
 
 **Import flexibility:**
@@ -151,6 +214,11 @@ svger-cli lock ./icons/critical-logo.svg  # Protects during all operations
 
 ## 📊 **Feature Comparison Matrix**
 
+> 📖 **For detailed technical analysis and documented benchmarks:**  
+> **[→ Read Complete Performance Deep Dive (COMPARISON.md)](./COMPARISON.md)**  
+> Includes: Benchmark methodology, dependency analysis, Webpack integration guide, and all 28
+> configuration options explained.
+
 | **Feature**                | **SVGER-CLI v2.0.7**       | **SVGR (React)** | **vite-svg-loader (Vue)** | **svelte-svg (Svelte)** | **SVGO**            |
 | -------------------------- | -------------------------- | ---------------- | ------------------------- | ----------------------- | ------------------- |
 | **Dependencies**           | ✅ **Zero**                | ❌ 15+ deps      | ❌ 9+ deps                | ❌ 7+ deps              | ❌ 8+ deps          |
@@ -185,6 +253,19 @@ engineered from the ground up with a single philosophy: **native, zero-dependenc
 This lean approach delivers up to **85% faster processing** and a **90% smaller bundle size**
 compared to alternatives that rely on dozens of transitive dependencies.
 
+> 📖 **Want to understand why it's faster?** Read the complete technical analysis with benchmarks,
+> methodology, and measurements:  
+> **[→ View Performance Deep Dive & Benchmarks (COMPARISON.md)](./COMPARISON.md)**
+>
+> Learn about:
+>
+> - Detailed benchmark methodology and test environment
+> - 4 architectural optimizations that deliver 85% improvement
+> - Memory usage comparison (12MB vs 68MB)
+> - Parallel processing performance (6.6x throughput)
+> - Smart caching system (99% hit rate)
+> - Real-world CI/CD impact and cost savings
+
 ---
 
 ## 📦 **Installation**
@@ -203,7 +284,284 @@ npm install --save-dev svger-cli
 
 ---
 
-## 🚀 **Quick Start: Your First Conversion**
+## � **Build Tool Integrations**
+
+**NEW in v3.0**: SVGER-CLI now provides official integrations for all major build tools, enabling
+seamless SVG-to-component conversion directly in your build pipeline.
+
+### Quick Integration Overview
+
+| Build Tool  | Package Import      | Use Case                | Key Features                     |
+| ----------- | ------------------- | ----------------------- | -------------------------------- |
+| **Webpack** | `svger-cli/webpack` | Modern web apps         | HMR, Watch mode, Loader support  |
+| **Vite**    | `svger-cli/vite`    | Lightning-fast dev      | HMR, Virtual modules, Dev server |
+| **Rollup**  | `svger-cli/rollup`  | Libraries & apps        | Tree-shaking, Source maps        |
+| **Babel**   | `svger-cli/babel`   | Universal transpilation | Import transform, CRA, Gatsby    |
+| **Next.js** | `svger-cli/nextjs`  | React SSR apps          | SSR support, App Router          |
+| **Jest**    | `svger-cli/jest`    | Testing                 | SVG mocking, Transformers        |
+
+### Webpack Integration
+
+Perfect for modern webpack-based applications with full HMR support.
+
+**Install:**
+
+```bash
+npm install svger-cli --save-dev
+```
+
+**webpack.config.js:**
+
+```javascript
+const { SvgerWebpackPlugin } = require('svger-cli/webpack');
+
+module.exports = {
+  plugins: [
+    new SvgerWebpackPlugin({
+      source: './src/icons', // SVG source directory
+      output: './src/components/icons', // Output directory
+      framework: 'react', // Target framework
+      typescript: true, // Generate TypeScript files
+      hmr: true, // Enable Hot Module Replacement
+      generateIndex: true, // Generate index.ts with exports
+    }),
+  ],
+
+  // Optional: Use the loader for inline SVG imports
+  module: {
+    rules: [
+      {
+        test: /\.svg$/,
+        use: ['svger-cli/webpack-loader'],
+      },
+    ],
+  },
+};
+```
+
+**Usage in your app:**
+
+```tsx
+import { HomeIcon, UserIcon } from './components/icons';
+
+function App() {
+  return <HomeIcon width={24} height={24} />;
+}
+```
+
+---
+
+### Vite Integration
+
+Lightning-fast development with HMR and virtual module support.
+
+**vite.config.js:**
+
+```javascript
+import { svgerVitePlugin } from 'svger-cli/vite';
+
+export default {
+  plugins: [
+    svgerVitePlugin({
+      source: './src/icons',
+      output: './src/components/icons',
+      framework: 'react',
+      typescript: true,
+      hmr: true, // Hot Module Replacement
+      virtualModules: true, // Enable virtual module imports
+    }),
+  ],
+};
+```
+
+**Features:**
+
+- ✅ Instant HMR - changes reflect immediately
+- ✅ Virtual modules - `import Icon from 'virtual:svger/icon-name'`
+- ✅ Dev server integration
+- ✅ Optimized production builds
+
+---
+
+### Rollup Integration
+
+Ideal for library development and tree-shakeable bundles.
+
+**rollup.config.js:**
+
+```javascript
+import { svgerRollupPlugin } from 'svger-cli/rollup';
+
+export default {
+  plugins: [
+    svgerRollupPlugin({
+      source: './src/icons',
+      output: './dist/icons',
+      framework: 'react',
+      typescript: true,
+      sourcemap: true, // Generate source maps
+      exportType: 'named', // 'named' or 'default'
+    }),
+  ],
+};
+```
+
+**Perfect for:**
+
+- Component libraries
+- Tree-shakeable exports
+- Multi-framework support
+- Production optimization
+
+---
+
+### Babel Integration
+
+Universal transpilation with automatic import transformation.
+
+**babel.config.js:**
+
+```javascript
+const { svgerBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  presets: ['@babel/preset-env', '@babel/preset-react'],
+  plugins: [
+    [
+      svgerBabelPlugin,
+      {
+        source: './src/icons',
+        output: './src/components/icons',
+        framework: 'react',
+        typescript: true,
+        transformImports: true, // Auto-transform SVG imports
+        processOnInit: true, // Process all SVGs on plugin init
+        generateIndex: true, // Generate barrel exports
+      },
+    ],
+  ],
+};
+```
+
+**Import transformation:**
+
+```javascript
+// Before (write this in your code)
+import HomeIcon from './assets/home.svg';
+
+// After (automatically transformed)
+import HomeIcon from './components/icons/HomeIcon';
+
+// Use it
+<HomeIcon width={24} height={24} />;
+```
+
+**Works with:**
+
+- Create React App
+- Gatsby
+- Vue CLI
+- Any Babel-based setup
+
+---
+
+### Next.js Integration
+
+Seamless integration with Next.js App Router and Pages Router.
+
+**next.config.js:**
+
+```javascript
+const { withSvger } = require('svger-cli/nextjs');
+
+module.exports = withSvger({
+  svger: {
+    source: './public/icons',
+    output: './components/icons',
+    framework: 'react',
+    typescript: true,
+    ssr: true, // Server-Side Rendering support
+    hmr: true, // Hot Module Replacement
+  },
+  // ...other Next.js config
+  reactStrictMode: true,
+});
+```
+
+**Features:**
+
+- ✅ SSR (Server-Side Rendering) support
+- ✅ App Router compatible
+- ✅ Pages Router compatible
+- ✅ Automatic webpack configuration
+- ✅ TypeScript support
+
+---
+
+### Jest Integration
+
+Transform SVGs in your tests or mock them for faster execution.
+
+**jest.config.js:**
+
+**Option 1: Use the preset (recommended)**
+
+```javascript
+module.exports = {
+  preset: 'svger-cli/jest',
+  testEnvironment: 'jsdom',
+};
+```
+
+**Option 2: Manual configuration**
+
+```javascript
+module.exports = {
+  transform: {
+    '\\.svg$': [
+      'svger-cli/jest-transformer',
+      {
+        framework: 'react',
+        typescript: true,
+        mock: false, // Set true for mock mode
+      },
+    ],
+  },
+  testEnvironment: 'jsdom',
+};
+```
+
+**Mock mode** (faster tests):
+
+```javascript
+transform: {
+  '\\.svg$': ['svger-cli/jest-transformer', {
+    mock: true,  // Returns simple mock component
+  }],
+}
+```
+
+---
+
+### Complete Integration Documentation
+
+For detailed documentation, configuration options, and advanced examples, see:
+
+📖 **[Complete Integration Guide](./docs/INTEGRATIONS.md)** - 500+ lines of comprehensive
+documentation
+
+**What's included:**
+
+- Detailed setup instructions for each build tool
+- All configuration options explained
+- Framework-specific examples (React, Vue, Angular, etc.)
+- Troubleshooting guides
+- Performance optimization tips
+- Feature comparison matrix
+
+---
+
+## �🚀 **Quick Start: Your First Conversion**
 
 1.  **Place your SVGs** in a directory (e.g., `./my-svgs`).
 2.  **Run the build command**:
@@ -2338,3 +2696,15 @@ instrumental in shaping the design and functionality of the SVGER-CLI v2.0.
 ---
 
 **© 2025 SVGER-CLI Development Team. Built with ❤️ for the developer community.**
+
+---
+
+## 📚 **Additional Documentation**
+
+- **[📊 Complete Feature Comparison & Benchmarks](./COMPARISON.md)** - Detailed technical analysis
+  with documented performance claims
+  - Benchmark methodology and test environment
+  - Detailed dependency tree analysis
+  - Webpack integration guide
+  - Complete configuration options breakdown
+  - Real-world performance examples

package/dist/index.d.ts

@@ -146,6 +146,36 @@ export declare const SVGER: {
  */
 export declare const VERSION = "2.0.0";
 export declare const PACKAGE_NAME = "svger-cli";
+/**
+ * Webpack Plugin - Official webpack integration for SVGER-CLI
+ * Provides: HMR support, asset processing, and webpack loader
+ */
+export { SvgerWebpackPlugin, svgerLoader, default as webpackPlugin, } from './integrations/webpack.js';
+/**
+ * Vite Plugin - Official Vite integration for SVGER-CLI
+ * Provides: HMR support, virtual modules, and dev server integration
+ */
+export { svgerVitePlugin, default as vitePlugin } from './integrations/vite.js';
+/**
+ * Rollup Plugin - Official Rollup integration for SVGER-CLI
+ * Provides: Bundle optimization and tree-shaking support
+ */
+export { svgerRollupPlugin, default as rollupPlugin, } from './integrations/rollup.js';
+/**
+ * Babel Plugin - Official Babel integration for SVGER-CLI
+ * Provides: SVG import transformation and component generation
+ */
+export { svgerBabelPlugin, createBabelPlugin, default as babelPlugin, } from './integrations/babel.js';
+/**
+ * Next.js Plugin - Official Next.js integration for SVGER-CLI
+ * Provides: SSR support, webpack integration, and HMR
+ */
+export { withSvger, SvgerNextJsPlugin, configureSvgImports, default as nextjsPlugin, } from './integrations/nextjs.js';
+/**
+ * Jest Preset - Official Jest integration for SVGER-CLI
+ * Provides: SVG transformers and test configuration
+ */
+export { svgerJestTransformer, jestPreset, createJestTransformer, default as jestTransformer, } from './integrations/jest-preset.js';
 /**
  * Default export - Primary SVG processor instance for quick access
  * Most common entry point for programmatic usage

package/dist/index.js

@@ -148,6 +148,39 @@ export const SVGER = {
 export const VERSION = '2.0.0';
 export const PACKAGE_NAME = 'svger-cli';
 // ============================================================================
+// BUILD TOOL INTEGRATIONS
+// ============================================================================
+/**
+ * Webpack Plugin - Official webpack integration for SVGER-CLI
+ * Provides: HMR support, asset processing, and webpack loader
+ */
+export { SvgerWebpackPlugin, svgerLoader, default as webpackPlugin, } from './integrations/webpack.js';
+/**
+ * Vite Plugin - Official Vite integration for SVGER-CLI
+ * Provides: HMR support, virtual modules, and dev server integration
+ */
+export { svgerVitePlugin, default as vitePlugin } from './integrations/vite.js';
+/**
+ * Rollup Plugin - Official Rollup integration for SVGER-CLI
+ * Provides: Bundle optimization and tree-shaking support
+ */
+export { svgerRollupPlugin, default as rollupPlugin, } from './integrations/rollup.js';
+/**
+ * Babel Plugin - Official Babel integration for SVGER-CLI
+ * Provides: SVG import transformation and component generation
+ */
+export { svgerBabelPlugin, createBabelPlugin, default as babelPlugin, } from './integrations/babel.js';
+/**
+ * Next.js Plugin - Official Next.js integration for SVGER-CLI
+ * Provides: SSR support, webpack integration, and HMR
+ */
+export { withSvger, SvgerNextJsPlugin, configureSvgImports, default as nextjsPlugin, } from './integrations/nextjs.js';
+/**
+ * Jest Preset - Official Jest integration for SVGER-CLI
+ * Provides: SVG transformers and test configuration
+ */
+export { svgerJestTransformer, jestPreset, createJestTransformer, default as jestTransformer, } from './integrations/jest-preset.js';
+// ============================================================================
 // DEFAULT EXPORT
 // ============================================================================
 /**

package/dist/integrations/babel.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Official Babel Plugin for SVGER-CLI
+ *
+ * Transforms SVG imports into framework components during Babel transpilation.
+ * Works with any Babel-based build process including standalone Babel, Create React App,
+ * and other tools that use Babel under the hood.
+ *
+ * @example
+ * ```js
+ * // babel.config.js
+ * const { svgerBabelPlugin } = require('svger-cli/babel');
+ *
+ * module.exports = {
+ *   plugins: [
+ *     [svgerBabelPlugin, {
+ *       source: './src/icons',
+ *       output: './src/components/icons',
+ *       framework: 'react',
+ *       typescript: true
+ *     }]
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```js
+ * // Direct SVG import transformation
+ * import Icon from './icon.svg';
+ * // Transforms to:
+ * import Icon from './components/icons/Icon';
+ * ```
+ */
+import type { BabelPluginOptions } from '../types/integrations.js';
+/**
+ * Babel Plugin for SVGER-CLI
+ *
+ * This plugin processes SVG files and transforms SVG imports to component imports.
+ * It can run in two modes:
+ * - Pre-build: Process all SVGs before Babel transformation
+ * - On-demand: Transform SVG imports as they're encountered
+ */
+export declare function svgerBabelPlugin(api: any, options?: BabelPluginOptions): any;
+/**
+ * Create a Babel plugin instance with preset options
+ *
+ * @example
+ * ```js
+ * const plugin = createBabelPlugin({
+ *   source: './icons',
+ *   framework: 'react'
+ * });
+ * ```
+ */
+export declare function createBabelPlugin(options?: BabelPluginOptions): (api: any) => any;
+/**
+ * Default export for convenient usage
+ */
+export default svgerBabelPlugin;