svger-cli 2.0.8 → 3.1.0

package/docs/INTEGRATIONS.md

@@ -0,0 +1,543 @@
+# SVGER-CLI Build Tool Integrations
+
+Official build tool integrations for SVGER-CLI, providing seamless SVG to component conversion in
+your existing build pipeline.
+
+## 🚀 Quick Start
+
+```bash
+npm install svger-cli --save-dev
+```
+
+## 📦 Available Integrations
+
+- **[Webpack](#webpack-integration)** - Plugin & Loader with HMR
+- **[Vite](#vite-integration)** - Plugin with HMR & Virtual Modules
+- **[Rollup](#rollup-integration)** - Plugin with Tree-Shaking
+- **[Babel](#babel-integration)** - Plugin with Import Transformation
+- **[Next.js](#nextjs-integration)** - Wrapper with SSR Support
+- **[Jest](#jest-integration)** - Preset & Transformer
+
+---
+
+## Webpack Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**webpack.config.js:**
+
+```javascript
+const { SvgerWebpackPlugin } = require('svger-cli/webpack');
+
+module.exports = {
+  plugins: [
+    new SvgerWebpackPlugin({
+      source: './src/icons',
+      output: './src/components/icons',
+      framework: 'react',
+      typescript: true,
+      hmr: true,
+      generateIndex: true,
+    }),
+  ],
+
+  module: {
+    rules: [
+      {
+        test: /\.svg$/,
+        use: [
+          {
+            loader: 'svger-cli/webpack-loader',
+            options: {
+              framework: 'react',
+              typescript: true,
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### Options
+
+| Option          | Type    | Default                    | Description                                  |
+| --------------- | ------- | -------------------------- | -------------------------------------------- |
+| `source`        | string  | `'./src/icons'`            | Source directory containing SVG files        |
+| `output`        | string  | `'./src/components/icons'` | Output directory for generated components    |
+| `framework`     | string  | `'react'`                  | Target framework (react, vue, angular, etc.) |
+| `typescript`    | boolean | `true`                     | Generate TypeScript files                    |
+| `hmr`           | boolean | `true`                     | Enable Hot Module Replacement                |
+| `generateIndex` | boolean | `true`                     | Generate index file with exports             |
+
+[See full example →](./examples/webpack.config.example.js)
+
+---
+
+## Vite Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**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,
+    }),
+  ],
+};
+```
+
+### Options
+
+| Option       | Type    | Default                    | Description                               |
+| ------------ | ------- | -------------------------- | ----------------------------------------- |
+| `source`     | string  | `'./src/icons'`            | Source directory containing SVG files     |
+| `output`     | string  | `'./src/components/icons'` | Output directory for generated components |
+| `framework`  | string  | `'react'`                  | Target framework                          |
+| `typescript` | boolean | `true`                     | Generate TypeScript files                 |
+| `hmr`        | boolean | `true`                     | Enable Hot Module Replacement             |
+| `virtual`    | boolean | `false`                    | Use virtual modules                       |
+| `exportType` | string  | `'default'`                | Export type ('default' or 'named')        |
+
+[See full example →](./examples/vite.config.example.js)
+
+---
+
+## Rollup Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**rollup.config.js:**
+
+```javascript
+import { svgerRollupPlugin } from 'svger-cli/rollup';
+
+export default {
+  plugins: [
+    svgerRollupPlugin({
+      source: './src/icons',
+      output: './src/components/icons',
+      framework: 'react',
+      typescript: true,
+      sourcemap: true,
+    }),
+  ],
+};
+```
+
+### Options
+
+| Option       | Type    | Default                    | Description                               |
+| ------------ | ------- | -------------------------- | ----------------------------------------- |
+| `source`     | string  | `'./src/icons'`            | Source directory containing SVG files     |
+| `output`     | string  | `'./src/components/icons'` | Output directory for generated components |
+| `framework`  | string  | `'react'`                  | Target framework                          |
+| `typescript` | boolean | `true`                     | Generate TypeScript files                 |
+| `sourcemap`  | boolean | `false`                    | Generate source maps                      |
+| `exportType` | string  | `'default'`                | Export type ('default' or 'named')        |
+
+[See full example →](./examples/rollup.config.example.js)
+
+---
+
+## Babel Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**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,
+        processOnInit: true,
+        generateIndex: true,
+      },
+    ],
+  ],
+};
+```
+
+**Or with ES Modules (babel.config.mjs):**
+
+```javascript
+import { svgerBabelPlugin } from 'svger-cli/babel';
+
+export default {
+  presets: ['@babel/preset-react'],
+  plugins: [
+    [
+      svgerBabelPlugin,
+      {
+        source: './src/icons',
+        output: './src/components/icons',
+        framework: 'react',
+      },
+    ],
+  ],
+};
+```
+
+### Features
+
+- ✅ **Import Transformation** - Automatically transforms SVG imports to component imports
+- ✅ **Dynamic Imports** - Supports `import('./icon.svg')` syntax
+- ✅ **Auto-Processing** - Processes all SVGs when plugin initializes
+- ✅ **Framework Agnostic** - Works with any Babel-based setup
+- ✅ **TypeScript Support** - Full type definitions included
+
+### How It Works
+
+```javascript
+// Before transformation
+import HomeIcon from './assets/home.svg';
+
+// After transformation (automatic)
+import HomeIcon from './components/icons/HomeIcon';
+
+// Use in your component
+function App() {
+  return <HomeIcon width={24} height={24} />;
+}
+```
+
+### Options
+
+| Option             | Type    | Default                    | Description                                  |
+| ------------------ | ------- | -------------------------- | -------------------------------------------- |
+| `source`           | string  | `'./src/icons'`            | Source directory containing SVG files        |
+| `output`           | string  | `'./src/components/icons'` | Output directory for generated components    |
+| `framework`        | string  | `'react'`                  | Target framework (react, vue, angular, etc.) |
+| `typescript`       | boolean | `true`                     | Generate TypeScript files                    |
+| `transformImports` | boolean | `true`                     | Transform SVG imports to component imports   |
+| `processOnInit`    | boolean | `true`                     | Process all SVGs when plugin initializes     |
+| `generateIndex`    | boolean | `true`                     | Generate index file with all exports         |
+| `include`          | array   | `['**/*.svg']`             | Glob patterns to include                     |
+| `exclude`          | array   | `['node_modules/**']`      | Glob patterns to exclude                     |
+
+### Use Cases
+
+**Create React App:**
+
+```javascript
+// babel-plugin-macros.config.js
+const { createBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  svger: createBabelPlugin({
+    source: './src/icons',
+    framework: 'react',
+  }),
+};
+```
+
+**Gatsby:**
+
+```javascript
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: 'gatsby-plugin-babel-plugin-svger',
+      options: {
+        source: './src/assets/icons',
+        framework: 'react',
+      },
+    },
+  ],
+};
+```
+
+**Vue CLI:**
+
+```javascript
+// babel.config.js
+const { svgerBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  presets: ['@vue/cli-plugin-babel/preset'],
+  plugins: [
+    [
+      svgerBabelPlugin,
+      {
+        source: './src/assets/icons',
+        framework: 'vue',
+      },
+    ],
+  ],
+};
+```
+
+[See full example →](./examples/babel.config.example.js)
+
+---
+
+## Next.js Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**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,
+  },
+  // ... other Next.js config
+});
+```
+
+### Options
+
+| Option       | Type    | Default                    | Description                               |
+| ------------ | ------- | -------------------------- | ----------------------------------------- |
+| `source`     | string  | `'./src/icons'`            | Source directory containing SVG files     |
+| `output`     | string  | `'./src/components/icons'` | Output directory for generated components |
+| `framework`  | string  | `'react'`                  | Always 'react' for Next.js                |
+| `typescript` | boolean | `true`                     | Generate TypeScript files                 |
+| `ssr`        | boolean | `true`                     | Enable Server-Side Rendering support      |
+| `hmr`        | boolean | `true`                     | Enable Hot Module Replacement             |
+
+[See full example →](./examples/next.config.example.js)
+
+---
+
+## Jest Integration
+
+### Installation
+
+```bash
+npm install svger-cli --save-dev
+```
+
+### Usage
+
+**jest.config.js:**
+
+```javascript
+module.exports = {
+  preset: 'svger-cli/jest',
+  testEnvironment: 'jsdom',
+};
+```
+
+**Or manually:**
+
+```javascript
+module.exports = {
+  transform: {
+    '\\.svg$': 'svger-cli/jest-transformer',
+  },
+};
+```
+
+### Options
+
+Configure through transformer config:
+
+```javascript
+transform: {
+  '\\.svg$': ['svger-cli/jest-transformer', {
+    framework: 'react',
+    typescript: true,
+    mock: false,  // Use simple mocks for faster tests
+  }],
+}
+```
+
+[See full example →](./examples/jest.config.example.js)
+
+---
+
+## 🎯 Usage Examples
+
+### React Component
+
+```tsx
+import { StarIcon, MenuIcon } from './components/icons';
+
+function App() {
+  return (
+    <div>
+      <StarIcon width={24} height={24} fill="gold" />
+      <MenuIcon />
+    </div>
+  );
+}
+```
+
+### Vue Component
+
+```vue
+<template>
+  <div>
+    <StarIcon :width="24" :height="24" fill="gold" />
+  </div>
+</template>
+
+<script setup>
+import { StarIcon } from './components/icons';
+</script>
+```
+
+### Angular Component
+
+```typescript
+import { Component } from '@angular/core';
+import { StarIconComponent } from './components/icons';
+
+@Component({
+  selector: 'app-root',
+  template: ` <app-star-icon [width]="24" [height]="24" fill="gold"></app-star-icon> `,
+  standalone: true,
+  imports: [StarIconComponent],
+})
+export class AppComponent {}
+```
+
+---
+
+## 🔧 Supported Frameworks
+
+All integrations support these frameworks:
+
+- ✅ React
+- ✅ React Native
+- ✅ Vue 3 (Composition & Options API)
+- ✅ Angular (Standalone & Module)
+- ✅ Svelte
+- ✅ Solid
+- ✅ Preact
+- ✅ Lit
+- ✅ Vanilla JS/TS
+
+---
+
+## 📚 Complete Examples
+
+Explore full working examples in the [`examples/`](./examples/) directory:
+
+- [Webpack Configuration](./examples/webpack.config.example.js)
+- [Vite Configuration](./examples/vite.config.example.js)
+- [Rollup Configuration](./examples/rollup.config.example.js)
+- [Babel Configuration](./examples/babel.config.example.js)
+- [Next.js Configuration](./examples/next.config.example.js)
+- [Jest Configuration](./examples/jest.config.example.js)
+
+---
+
+## 🚀 Features
+
+### All Integrations Include:
+
+- ✅ **Zero Dependencies** - No bloat
+- ✅ **TypeScript Support** - Full type safety
+- ✅ **Framework Agnostic** - Works with all major frameworks
+- ✅ **Tree Shaking** - Bundle only what you use
+- ✅ **Auto-Generated Exports** - Convenient barrel files
+- ✅ **85% Faster** - Than alternatives like SVGR
+
+### Build Tool Specific:
+
+| Feature            | Webpack | Vite | Rollup | Babel | Next.js | Jest |
+| ------------------ | ------- | ---- | ------ | ----- | ------- | ---- |
+| HMR Support        | ✅      | ✅   | ❌     | ❌    | ✅      | N/A  |
+| Source Maps        | ✅      | ✅   | ✅     | ❌    | ✅      | ❌   |
+| SSR Support        | ❌      | ✅   | ❌     | ❌    | ✅      | N/A  |
+| Virtual Modules    | ❌      | ✅   | ❌     | ❌    | ❌      | N/A  |
+| Watch Mode         | ✅      | ✅   | ✅     | ✅    | ✅      | N/A  |
+| Import Transform   | ✅      | ✅   | ✅     | ✅    | ✅      | ✅   |
+| Dynamic Imports    | ✅      | ✅   | ✅     | ✅    | ✅      | ❌   |
+| Framework Agnostic | ✅      | ✅   | ✅     | ✅    | ❌      | ✅   |
+
+---
+
+## 🧪 Testing
+
+Run integration tests:
+
+```bash
+npm run test:integrations
+```
+
+All integrations are thoroughly tested and verified to work correctly.
+
+---
+
+## 📖 Documentation
+
+For complete documentation, visit the [main README](../README.md) or check out specific guides:
+
+- [CLI Documentation](../README.md#-comprehensive-cli-reference)
+- [Configuration Reference](../README.md#-configuration-reference)
+- [API Documentation](../README.md#-programmatic-api)
+
+---
+
+## 💬 Support
+
+- 📝 [Report Issues](https://github.com/navidrezadoost/svger-cli/issues)
+- 💡 [Request Features](https://github.com/navidrezadoost/svger-cli/issues/new)
+- 📖 [Read Docs](../README.md)
+
+---
+
+## 📄 License
+
+MIT © SVGER-CLI Development Team

package/examples/babel.config.example.js

@@ -0,0 +1,182 @@
+/**
+ * Example Babel Configuration for SVGER-CLI
+ *
+ * This example shows how to use the SVGER Babel plugin to automatically
+ * convert SVG files to framework components during transpilation.
+ *
+ * The plugin works with any Babel-based build process including:
+ * - Standalone Babel
+ * - Create React App
+ * - Gatsby
+ * - Any tool using Babel under the hood
+ */
+
+// Option 1: Using require (CommonJS)
+const { svgerBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  presets: [
+    '@babel/preset-env',
+    '@babel/preset-react',
+    '@babel/preset-typescript',
+  ],
+  plugins: [
+    // Add SVGER plugin with configuration
+    [
+      svgerBabelPlugin,
+      {
+        // Source directory containing SVG files
+        source: './src/icons',
+
+        // Output directory for generated components
+        output: './src/components/icons',
+
+        // Target framework
+        framework: 'react',
+
+        // Use TypeScript
+        typescript: true,
+
+        // Transform SVG imports to component imports
+        // When enabled: import Icon from './icon.svg' -> import Icon from './components/icons/Icon'
+        transformImports: true,
+
+        // Process all SVGs when plugin is initialized
+        // Recommended for production builds
+        processOnInit: true,
+
+        // Generate index file with all components
+        generateIndex: true,
+
+        // Glob patterns to include
+        include: ['**/*.svg'],
+
+        // Glob patterns to exclude
+        exclude: ['node_modules/**'],
+      },
+    ],
+  ],
+};
+
+// Option 2: Using ES Modules (in babel.config.mjs)
+/*
+import { svgerBabelPlugin } from 'svger-cli/babel';
+
+export default {
+  presets: [
+    '@babel/preset-env',
+    '@babel/preset-react'
+  ],
+  plugins: [
+    [svgerBabelPlugin, {
+      source: './src/icons',
+      output: './src/components/icons',
+      framework: 'react',
+      typescript: true
+    }]
+  ]
+};
+*/
+
+// Option 3: Create React App (babel-plugin-macros.config.js)
+/*
+const { createBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  svger: createBabelPlugin({
+    source: './src/icons',
+    output: './src/components/icons',
+    framework: 'react'
+  })
+};
+*/
+
+// Option 4: Minimal configuration (uses defaults from .svgerconfig)
+/*
+module.exports = {
+  presets: ['@babel/preset-react'],
+  plugins: [
+    // Simple usage - reads config from .svgerconfig
+    require('svger-cli/babel').svgerBabelPlugin
+  ]
+};
+*/
+
+// Option 5: Vue.js example
+/*
+const { svgerBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  presets: ['@vue/cli-plugin-babel/preset'],
+  plugins: [
+    [svgerBabelPlugin, {
+      source: './src/assets/icons',
+      output: './src/components/icons',
+      framework: 'vue',
+      typescript: false
+    }]
+  ]
+};
+*/
+
+// Option 6: Angular example
+/*
+const { svgerBabelPlugin } = require('svger-cli/babel');
+
+module.exports = {
+  presets: ['@babel/preset-typescript'],
+  plugins: [
+    [svgerBabelPlugin, {
+      source: './src/assets/svg',
+      output: './src/app/components/icons',
+      framework: 'angular',
+      typescript: true
+    }]
+  ]
+};
+*/
+
+/**
+ * Configuration Options Reference:
+ *
+ * @param {string} source - Source directory containing SVG files
+ * @param {string} output - Output directory for generated components
+ * @param {string} framework - Target framework (react, vue, angular, svelte, etc.)
+ * @param {boolean} typescript - Generate TypeScript files (.tsx instead of .jsx)
+ * @param {boolean} transformImports - Transform SVG imports to component imports
+ * @param {boolean} processOnInit - Process all SVGs when plugin initializes
+ * @param {boolean} generateIndex - Generate index.ts/js with all exports
+ * @param {string|string[]} include - Glob patterns to include
+ * @param {string|string[]} exclude - Glob patterns to exclude
+ * @param {object} config - Advanced configuration (see .svgerconfig docs)
+ *
+ * Features:
+ * - ✅ Automatic SVG to component conversion during build
+ * - ✅ Import transformation (import Icon from './icon.svg')
+ * - ✅ Dynamic import support (import('./icon.svg'))
+ * - ✅ Framework-agnostic (React, Vue, Angular, Svelte, etc.)
+ * - ✅ TypeScript support with type definitions
+ * - ✅ Auto-generated barrel exports (index files)
+ * - ✅ Watch mode compatible
+ * - ✅ Works with Create React App, Gatsby, and more
+ *
+ * How it works:
+ * 1. Plugin processes all SVGs in source directory on initialization
+ * 2. Generates framework-specific components in output directory
+ * 3. Transforms SVG imports in your code to component imports
+ * 4. Creates index file with all component exports
+ *
+ * Usage in your code:
+ * ```jsx
+ * // Before (with transformImports: true)
+ * import HomeIcon from './assets/home.svg';
+ *
+ * // After transformation (automatic)
+ * import HomeIcon from './components/icons/HomeIcon';
+ *
+ * // Use the component
+ * function App() {
+ *   return <HomeIcon width={24} height={24} />;
+ * }
+ * ```
+ */