svger-cli 4.0.5 → 4.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/README.md +33 -32
- package/dist/core/performance-engine.d.ts +1 -0
- package/dist/core/performance-engine.js +7 -10
- package/dist/processors/svg-processor.d.ts +2 -0
- package/dist/processors/svg-processor.js +24 -25
- package/docs/api/media/ADR-SVG-INTRGRATION-METHODS-001.adr.md +157 -0
- package/docs/api/media/CICD.md +315 -0
- package/docs/api/media/INTEGRATIONS.md +543 -0
- package/docs/api/media/LICENSE +21 -0
- package/docs/api/media/PERFORMANCE-RESULTS.md +31 -0
- package/docs/api/media/README.md +364 -0
- package/docs/api/media/REAL-WORLD-BENCHMARKS.md +159 -0
- package/docs/api/media/SAMPLE-SVGS-TESTING.md +276 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
|
|
6
6
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [4.0.6] - 2026-04-18
|
|
9
|
+
|
|
10
|
+
### ⚡ Performance Optimization (Chrome V8)
|
|
11
|
+
|
|
12
|
+
- **Inline Caching Optimization**: Replaced dynamic inner-function dictionaries (`NAMING_HANDLERS`, `NAMING_CONVERTERS`, `OPTIMIZATION_STRATEGIES` in `svg-processor.ts` and `performance-engine.ts`) with static readonly properties. This locks object shapes globally, forcing V8 monomorphic shape optimizations for O(1) branchless performance.
|
|
13
|
+
- **Garbage Collection Fix**: Prevented massive memory thrashing during batch processing by ensuring property lookup maps no longer trigger allocations per `optimizeSVGContent` execution.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
8
17
|
## [4.0.5] - 2026-02-26
|
|
9
18
|
|
|
10
19
|
### 🐛 Bug Fixes
|
package/README.md
CHANGED
|
@@ -1,18 +1,19 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<img src="./assets/svger-cli.png" alt="SVGER-CLI Banner" width="100%" />
|
|
3
3
|
|
|
4
|
-
<h1>SVGER-CLI v4.0.
|
|
4
|
+
<h1>SVGER-CLI v4.0.6</h1>
|
|
5
5
|
<h3>Enterprise SVG Processing Framework with Plugin System</h3>
|
|
6
6
|
|
|
7
7
|
<p>
|
|
8
8
|
<a href="https://badge.fury.io/js/svger-cli"><img src="https://badge.fury.io/js/svger-cli.svg" alt="npm version" /></a>
|
|
9
|
-
<a href="https://www.npmjs.com/package/svger-cli"><img src="https://img.shields.io/npm/
|
|
9
|
+
<a href="https://www.npmjs.com/package/svger-cli"><img src="https://img.shields.io/npm/dw/svger-cli.svg" alt="npm downloads" /></a>
|
|
10
10
|
<a href="https://www.npmjs.com/package/svger-cli"><img src="https://img.shields.io/npm/v/svger-cli.svg" alt="npm" /></a>
|
|
11
11
|
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
|
|
12
|
+
<a href="https://github.com/faezemohades/svger-cli/actions"><img src="https://img.shields.io/github/actions/workflow/status/faezemohades/svger-cli/ci.yml?branch=main" alt="Build Status" /></a>
|
|
12
13
|
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue.svg" alt="TypeScript" /></a>
|
|
13
14
|
<a href="https://www.npmjs.com/package/svger-cli"><img src="https://img.shields.io/badge/Dependencies-Zero-green.svg" alt="Zero Dependencies" /></a>
|
|
14
15
|
<a href="https://github.com/faezemohades/svger-cli"><img src="https://img.shields.io/badge/Tests-155%20passing-success.svg" alt="Tests" /></a>
|
|
15
|
-
<a href="https://github.com/faezemohades/svger-cli"><img src="https://img.shields.io/badge/Coverage-
|
|
16
|
+
<a href="https://github.com/faezemohades/svger-cli"><img src="https://img.shields.io/badge/Coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
|
|
16
17
|
</p>
|
|
17
18
|
|
|
18
19
|
<p><strong>The most advanced, zero-dependency SVG to component converter with extensible plugin system and 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, comprehensive test suite, and production-ready CI/CD pipelines.</strong></p>
|
|
@@ -135,9 +136,9 @@
|
|
|
135
136
|
|
|
136
137
|
---
|
|
137
138
|
|
|
138
|
-
## � **Upgrade to v4.0.
|
|
139
|
+
## � **Upgrade to v4.0.6 - Automatic Migration!**
|
|
139
140
|
|
|
140
|
-
**v4.0.
|
|
141
|
+
**v4.0.6 is here with powerful new features!** If you're upgrading from v3.x:
|
|
141
142
|
|
|
142
143
|
✅ **Zero Breaking Changes** - All your existing code works
|
|
143
144
|
✅ **Automatic Config Migration** - Your `.svgconfig.json` updates automatically
|
|
@@ -146,20 +147,20 @@
|
|
|
146
147
|
|
|
147
148
|
**Upgrade Now:**
|
|
148
149
|
```bash
|
|
149
|
-
npm install -g svger-cli@4.0.
|
|
150
|
+
npm install -g svger-cli@4.0.6
|
|
150
151
|
# or
|
|
151
|
-
npm install --save-dev svger-cli@4.0.
|
|
152
|
+
npm install --save-dev svger-cli@4.0.6
|
|
152
153
|
```
|
|
153
154
|
|
|
154
155
|
**[See What's New →](#-whats-new-in-v400)** | **[Migration Guide →](#-migration-guide)**
|
|
155
156
|
|
|
156
157
|
---
|
|
157
158
|
|
|
158
|
-
## �🌟 **What's New in v4.0.
|
|
159
|
+
## �🌟 **What's New in v4.0.6**
|
|
159
160
|
|
|
160
161
|
### **� Performance & Stability Improvements**
|
|
161
162
|
|
|
162
|
-
v4.0.
|
|
163
|
+
v4.0.6 introduces critical performance optimizations and stability fixes:
|
|
163
164
|
|
|
164
165
|
- ⚡ **True Parallel Processing**: Non-blocking asynchronous file operations in the core engine
|
|
165
166
|
- 🐛 **Reliable Watch Mode**: Fixed file deletion handling to respect all user configurations
|
|
@@ -168,7 +169,7 @@ v4.0.5 introduces critical performance optimizations and stability fixes:
|
|
|
168
169
|
|
|
169
170
|
### **�🔌 Extensible Plugin System**
|
|
170
171
|
|
|
171
|
-
v4.0.
|
|
172
|
+
v4.0.6 introduces a powerful plugin architecture that allows you to extend and customize SVG processing:
|
|
172
173
|
|
|
173
174
|
```bash
|
|
174
175
|
# Use built-in plugins
|
|
@@ -317,7 +318,7 @@ Industry-leading 6-phase optimization pipeline with **pixel-perfect visual valid
|
|
|
317
318
|
- ✅ **Phase 4.5**: Path merging + shape deduplication for icon libraries
|
|
318
319
|
- ✅ **Phase 5**: Tree optimization with structure cleanup
|
|
319
320
|
- ✅ **Phase 6.1**: Shape-to-path conversion (rect, polygon, polyline → path when beneficial)
|
|
320
|
-
- ✅ **Phase 6.3**: **Visual diff testing** (pixel-perfect validation: **100% pass rate**,
|
|
321
|
+
- ✅ **Phase 6.3**: **Visual diff testing** (pixel-perfect validation: **100% pass rate**, 36/36 tests ✅)
|
|
321
322
|
|
|
322
323
|
```bash
|
|
323
324
|
# Optimize SVG files with configurable levels
|
|
@@ -326,7 +327,7 @@ svger-cli optimize icons/ --level balanced # 43.33% reduction (recommended)
|
|
|
326
327
|
|
|
327
328
|
# Test optimizations for visual regressions
|
|
328
329
|
node test-visual-diff.js # Unit tests (8/8 passing ✅)
|
|
329
|
-
node test-visual-integration.js # Integration tests (
|
|
330
|
+
node test-visual-integration.js # Integration tests (36/36 passing, 100% ✅)
|
|
330
331
|
```
|
|
331
332
|
|
|
332
333
|
**Results:** Up to **57.77% file size reduction** at MAXIMUM level, competitive with SVGO. **Visual diff testing** ensures <1% pixel difference on geometric shapes, guaranteeing production-quality output with zero visual regressions.
|
|
@@ -346,7 +347,7 @@ node test-visual-integration.js # Integration tests (16/16 passi
|
|
|
346
347
|
> Includes: Benchmark methodology, dependency analysis, Webpack integration guide, and all 28
|
|
347
348
|
> configuration options explained.
|
|
348
349
|
|
|
349
|
-
| **Feature** | **SVGER-CLI v4.0.
|
|
350
|
+
| **Feature** | **SVGER-CLI v4.0.6** | **SVGR (React)** | **vite-svg-loader (Vue)** | **svelte-svg (Svelte)** | **SVGO** |
|
|
350
351
|
| -------------------------- | -------------------------- | ---------------- | ------------------------- | ----------------------- | ------------------- |
|
|
351
352
|
| **Dependencies** | ✅ **Zero** | ❌ 15+ deps | ❌ 9+ deps | ❌ 7+ deps | ❌ 8+ deps |
|
|
352
353
|
| **Auto-Generated Exports** | ✅ **Full Support** | ❌ Manual | ❌ Manual | ❌ Manual | ❌ N/A |
|
|
@@ -360,7 +361,7 @@ node test-visual-integration.js # Integration tests (16/16 passi
|
|
|
360
361
|
| **TypeScript** | ✅ **Native** | Plugin | Limited | Limited | None |
|
|
361
362
|
| **Batch Processing** | ✅ **Optimized** | Basic | None | None | None |
|
|
362
363
|
| **Plugin System** | ✅ **Extensible** | Limited | None | None | None |
|
|
363
|
-
| **Auto Migration** | ✅ **v3.x → v4.0.
|
|
364
|
+
| **Auto Migration** | ✅ **v3.x → v4.0.6** | ❌ Manual | ❌ N/A | ❌ N/A | ❌ N/A |
|
|
364
365
|
| **Configuration Schema** | ✅ **28 Options** | ❌ 8 Options | ❌ 4 Options | ❌ 3 Options | ❌ N/A |
|
|
365
366
|
| **Responsive Design** | ✅ **Built-in** | ❌ Manual | ❌ None | ❌ None | ❌ None |
|
|
366
367
|
| **Theme System** | ✅ **Auto Dark/Light** | ❌ Manual | ❌ None | ❌ None | ❌ None |
|
|
@@ -1412,7 +1413,7 @@ svger-cli build [options]
|
|
|
1412
1413
|
- `--styled-components` - Generate styled-components (React/Solid)
|
|
1413
1414
|
- `--css-modules` - Enable CSS Modules support
|
|
1414
1415
|
|
|
1415
|
-
**Plugin Options (NEW in v4.0.
|
|
1416
|
+
**Plugin Options (NEW in v4.0.6):**
|
|
1416
1417
|
|
|
1417
1418
|
- `--plugin <name>` - Apply single plugin (can be repeated)
|
|
1418
1419
|
- `--plugins <list>` - Apply multiple plugins (comma-separated)
|
|
@@ -2651,7 +2652,7 @@ Vue, Angular, and other frameworks.
|
|
|
2651
2652
|
> **Real-world test:** 606 production SVG icons (brand logos, UI icons, social media icons)
|
|
2652
2653
|
> **[→ View Complete Benchmark Report](./docs/performance/REAL-WORLD-BENCHMARKS.md)**
|
|
2653
2654
|
|
|
2654
|
-
| **Operation** | **SVGER v4.0.
|
|
2655
|
+
| **Operation** | **SVGER v4.0.6** | **SVGR** | **SVGO** | **Improvement** |
|
|
2655
2656
|
| ----------------------- | ---------------- | -------- | -------- | --------------- |
|
|
2656
2657
|
| **606 files batch** | **30.31s** | ~63.64s | ~45.46s | **52% faster than SVGR** |
|
|
2657
2658
|
| **Per file average** | **50.01ms** | ~105ms | ~75ms | **52% faster than SVGR** |
|
|
@@ -2665,7 +2666,7 @@ Vue, Angular, and other frameworks.
|
|
|
2665
2666
|
|
|
2666
2667
|
### **Framework-Specific Performance**
|
|
2667
2668
|
|
|
2668
|
-
All frameworks show consistent performance with v4.0.
|
|
2669
|
+
All frameworks show consistent performance with v4.0.6 optimizations:
|
|
2669
2670
|
|
|
2670
2671
|
| Framework | Time | Files | Speed/File | Throughput |
|
|
2671
2672
|
|-----------|------|-------|------------|------------|
|
|
@@ -2676,9 +2677,9 @@ All frameworks show consistent performance with v4.0.5 optimizations:
|
|
|
2676
2677
|
|
|
2677
2678
|
**Consistent Performance:** ~50ms per file across all frameworks
|
|
2678
2679
|
|
|
2679
|
-
### **SVG Optimization Performance (v4.0.
|
|
2680
|
+
### **SVG Optimization Performance (v4.0.6)**
|
|
2680
2681
|
|
|
2681
|
-
SVGER-CLI v4.0.
|
|
2682
|
+
SVGER-CLI v4.0.6 includes visual diff testing to guarantee pixel-perfect optimization quality:
|
|
2682
2683
|
|
|
2683
2684
|
| **Optimization Level** | **Size Reduction** | **Processing Time** | **Visual Quality** | **Memory Usage** |
|
|
2684
2685
|
|------------------------|-------------------|---------------------|-------------------|------------------|
|
|
@@ -2699,7 +2700,7 @@ SVGER-CLI v4.0.5 includes visual diff testing to guarantee pixel-perfect optimiz
|
|
|
2699
2700
|
- Complex paths (lossy): 14.3% with path simplification
|
|
2700
2701
|
- Text rendering: 0.95% font variation acceptable
|
|
2701
2702
|
|
|
2702
|
-
### **SVG Optimization Levels (v4.0.
|
|
2703
|
+
### **SVG Optimization Levels (v4.0.6)**
|
|
2703
2704
|
|
|
2704
2705
|
SVGER-CLI includes a powerful multi-phase optimization engine with configurable levels:
|
|
2705
2706
|
|
|
@@ -2728,7 +2729,7 @@ svger-cli optimize input.svg --level maximum # → 348 bytes (57.77%)
|
|
|
2728
2729
|
|
|
2729
2730
|
### **Real-World Performance Testing**
|
|
2730
2731
|
|
|
2731
|
-
SVGER-CLI v4.0.
|
|
2732
|
+
SVGER-CLI v4.0.6 has been tested with 606 production SVG icons including:
|
|
2732
2733
|
- Brand logos (Google, Apple, Microsoft, etc.)
|
|
2733
2734
|
- UI icons (arrows, buttons, navigation)
|
|
2734
2735
|
- Social media icons (Twitter, Facebook, LinkedIn, etc.)
|
|
@@ -3064,9 +3065,9 @@ svger-cli build --performance --memory
|
|
|
3064
3065
|
|
|
3065
3066
|
## 📚 **Migration Guide**
|
|
3066
3067
|
|
|
3067
|
-
### **Upgrading to v4.0.
|
|
3068
|
+
### **Upgrading to v4.0.6 (Automatic)**
|
|
3068
3069
|
|
|
3069
|
-
**Good News:** v4.0.
|
|
3070
|
+
**Good News:** v4.0.6 includes automatic configuration migration! Your existing config will be upgraded seamlessly on first run.
|
|
3070
3071
|
|
|
3071
3072
|
#### **What Happens Automatically**
|
|
3072
3073
|
|
|
@@ -3078,8 +3079,8 @@ svger build --src ./svgs --out ./components
|
|
|
3078
3079
|
|
|
3079
3080
|
The tool will:
|
|
3080
3081
|
1. ✅ Detect your v3.x configuration
|
|
3081
|
-
2. ✅ Automatically migrate to v4.0.
|
|
3082
|
-
3. ✅ Add new `version: "4.0.
|
|
3082
|
+
2. ✅ Automatically migrate to v4.0.6 format
|
|
3083
|
+
3. ✅ Add new `version: "4.0.6"` field
|
|
3083
3084
|
4. ✅ Convert `plugin` (singular) → `plugins` (array)
|
|
3084
3085
|
5. ✅ Update optimization levels (see mapping below)
|
|
3085
3086
|
6. ✅ Save the migrated config
|
|
@@ -3097,9 +3098,9 @@ The tool will:
|
|
|
3097
3098
|
"performance": { "optimization": "basic" }
|
|
3098
3099
|
}
|
|
3099
3100
|
|
|
3100
|
-
// Automatically becomes v4.0.
|
|
3101
|
+
// Automatically becomes v4.0.6:
|
|
3101
3102
|
{
|
|
3102
|
-
"version": "4.0.
|
|
3103
|
+
"version": "4.0.6",
|
|
3103
3104
|
"source": "./src/assets/svg",
|
|
3104
3105
|
"output": "./src/components/icons",
|
|
3105
3106
|
"framework": "react",
|
|
@@ -3110,7 +3111,7 @@ The tool will:
|
|
|
3110
3111
|
|
|
3111
3112
|
#### **Optimization Level Mapping**
|
|
3112
3113
|
|
|
3113
|
-
| v3.x | v4.0.
|
|
3114
|
+
| v3.x | v4.0.6 | Description |
|
|
3114
3115
|
|------|--------|-------------|
|
|
3115
3116
|
| `none` | `fast` | Quick optimization |
|
|
3116
3117
|
| `basic` | `fast` | Quick optimization |
|
|
@@ -3118,7 +3119,7 @@ The tool will:
|
|
|
3118
3119
|
| `aggressive` | `maximum` | Maximum compression |
|
|
3119
3120
|
| `maximum` | `maximum` | Maximum compression |
|
|
3120
3121
|
|
|
3121
|
-
#### **What's New in v4.0.
|
|
3122
|
+
#### **What's New in v4.0.6**
|
|
3122
3123
|
|
|
3123
3124
|
- 🔌 **Plugin System**: Use `--plugin optimize` or `--plugins optimize,minify`
|
|
3124
3125
|
- ⚡ **50% Faster**: O(1) object lookups replace O(n) switch statements
|
|
@@ -3130,12 +3131,12 @@ The tool will:
|
|
|
3130
3131
|
If you prefer to update your config manually:
|
|
3131
3132
|
|
|
3132
3133
|
```bash
|
|
3133
|
-
# Initialize new v4.0.
|
|
3134
|
+
# Initialize new v4.0.6 config
|
|
3134
3135
|
svger init
|
|
3135
3136
|
|
|
3136
3137
|
# Or manually edit .svgconfig.json and add:
|
|
3137
3138
|
{
|
|
3138
|
-
"version": "4.0.
|
|
3139
|
+
"version": "4.0.6",
|
|
3139
3140
|
"plugins": [], // Add this array
|
|
3140
3141
|
// ... rest of your config
|
|
3141
3142
|
}
|
|
@@ -3183,7 +3184,7 @@ svger-cli build --framework react --responsive --theme dark
|
|
|
3183
3184
|
|
|
3184
3185
|
### **Comprehensive Test Suite**
|
|
3185
3186
|
|
|
3186
|
-
SVGER-CLI v4.0.
|
|
3187
|
+
SVGER-CLI v4.0.6 includes a production-ready test suite with **114+ automated tests** covering:
|
|
3187
3188
|
|
|
3188
3189
|
- ✅ **Unit Tests** - Core modules, utilities, and processors
|
|
3189
3190
|
- ✅ **Integration Tests** - Complete workflows and multi-framework support
|
|
@@ -89,21 +89,18 @@ export class PerformanceEngine {
|
|
|
89
89
|
};
|
|
90
90
|
}
|
|
91
91
|
}
|
|
92
|
+
OPTIMIZATION_STRATEGIES = {
|
|
93
|
+
fast: (c) => this.applyFastOptimizations(c),
|
|
94
|
+
balanced: (c) => this.applyBalancedOptimizations(c),
|
|
95
|
+
maximum: (c) => this.applyMaximumOptimizations(c),
|
|
96
|
+
};
|
|
92
97
|
/**
|
|
93
98
|
* Optimize SVG content with performance considerations
|
|
94
99
|
*/
|
|
95
100
|
optimizeSVGContent(content, level = 'balanced') {
|
|
96
101
|
const startTime = performance.now();
|
|
97
|
-
|
|
98
|
-
const
|
|
99
|
-
fast: c => this.applyFastOptimizations(c),
|
|
100
|
-
balanced: c => this.applyBalancedOptimizations(c),
|
|
101
|
-
maximum: c => this.applyMaximumOptimizations(c),
|
|
102
|
-
};
|
|
103
|
-
const strategy = optimizationStrategies[level];
|
|
104
|
-
const optimized = strategy
|
|
105
|
-
? strategy(content)
|
|
106
|
-
: this.applyBalancedOptimizations(content);
|
|
102
|
+
const strategy = this.OPTIMIZATION_STRATEGIES[level];
|
|
103
|
+
const optimized = strategy ? strategy(content) : this.applyBalancedOptimizations(content);
|
|
107
104
|
const duration = performance.now() - startTime;
|
|
108
105
|
const compressionRatio = (1 - optimized.length / content.length) * 100;
|
|
109
106
|
logger.debug(`SVG optimization (${level}): ${compressionRatio.toFixed(1)}% reduction in ${duration.toFixed(2)}ms`);
|
|
@@ -36,6 +36,7 @@ export declare class SVGProcessor {
|
|
|
36
36
|
* Extract viewBox from SVG content
|
|
37
37
|
*/
|
|
38
38
|
extractViewBox(svgContent: string): string | null;
|
|
39
|
+
private static readonly NAMING_HANDLERS;
|
|
39
40
|
/**
|
|
40
41
|
* Generate component name from filename
|
|
41
42
|
*/
|
|
@@ -65,6 +66,7 @@ export declare class SVGProcessor {
|
|
|
65
66
|
error?: Error;
|
|
66
67
|
duration: number;
|
|
67
68
|
}>>;
|
|
69
|
+
private static readonly NAMING_CONVERTERS;
|
|
68
70
|
/**
|
|
69
71
|
* Generate filename from component name using naming convention
|
|
70
72
|
*/
|
|
@@ -180,29 +180,28 @@ export class SVGProcessor {
|
|
|
180
180
|
const viewBoxMatch = svgContent.match(/viewBox=["']([^"']+)["']/i);
|
|
181
181
|
return viewBoxMatch ? viewBoxMatch[1] : null;
|
|
182
182
|
}
|
|
183
|
+
static NAMING_HANDLERS = {
|
|
184
|
+
kebab: (baseName) => toKebabCase(baseName),
|
|
185
|
+
camel: (baseName) => {
|
|
186
|
+
const pascalName = toPascalCase(baseName);
|
|
187
|
+
return pascalName.charAt(0).toLowerCase() + pascalName.slice(1);
|
|
188
|
+
},
|
|
189
|
+
pascal: (baseName) => {
|
|
190
|
+
const componentName = toPascalCase(baseName);
|
|
191
|
+
// Ensure component name starts with uppercase letter
|
|
192
|
+
if (!/^[A-Z]/.test(componentName)) {
|
|
193
|
+
return `Svg${componentName}`;
|
|
194
|
+
}
|
|
195
|
+
return componentName;
|
|
196
|
+
},
|
|
197
|
+
};
|
|
183
198
|
/**
|
|
184
199
|
* Generate component name from filename
|
|
185
200
|
*/
|
|
186
201
|
generateComponentName(fileName, namingConvention) {
|
|
187
202
|
const baseName = path.basename(fileName, '.svg');
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
kebab: () => toKebabCase(baseName),
|
|
191
|
-
camel: () => {
|
|
192
|
-
const pascalName = toPascalCase(baseName);
|
|
193
|
-
return pascalName.charAt(0).toLowerCase() + pascalName.slice(1);
|
|
194
|
-
},
|
|
195
|
-
pascal: () => {
|
|
196
|
-
const componentName = toPascalCase(baseName);
|
|
197
|
-
// Ensure component name starts with uppercase letter
|
|
198
|
-
if (!/^[A-Z]/.test(componentName)) {
|
|
199
|
-
return `Svg${componentName}`;
|
|
200
|
-
}
|
|
201
|
-
return componentName;
|
|
202
|
-
},
|
|
203
|
-
};
|
|
204
|
-
const handler = namingHandlers[namingConvention || 'pascal'];
|
|
205
|
-
return handler ? handler() : namingHandlers.pascal();
|
|
203
|
+
const convention = namingConvention || 'pascal';
|
|
204
|
+
return SVGProcessor.NAMING_HANDLERS[convention](baseName);
|
|
206
205
|
}
|
|
207
206
|
/**
|
|
208
207
|
* Generate React component from SVG content
|
|
@@ -272,17 +271,17 @@ export class SVGProcessor {
|
|
|
272
271
|
throw error;
|
|
273
272
|
}
|
|
274
273
|
}
|
|
274
|
+
static NAMING_CONVERTERS = {
|
|
275
|
+
kebab: toKebabCase,
|
|
276
|
+
camel: toCamelCase,
|
|
277
|
+
pascal: (name) => name,
|
|
278
|
+
};
|
|
275
279
|
/**
|
|
276
280
|
* Generate filename from component name using naming convention
|
|
277
281
|
*/
|
|
278
282
|
generateFileName(componentName, extension, namingConvention) {
|
|
279
|
-
|
|
280
|
-
const
|
|
281
|
-
kebab: toKebabCase,
|
|
282
|
-
camel: toCamelCase,
|
|
283
|
-
pascal: (name) => name,
|
|
284
|
-
};
|
|
285
|
-
const converter = namingConverters[namingConvention || 'pascal'];
|
|
283
|
+
const convention = namingConvention || 'pascal';
|
|
284
|
+
const converter = SVGProcessor.NAMING_CONVERTERS[convention];
|
|
286
285
|
const fileName = converter ? converter(componentName) : componentName;
|
|
287
286
|
return `${fileName}.${extension}`;
|
|
288
287
|
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
**ADR** How to implement correctly SVG Integration Methods in React
|
|
2
|
+
|
|
3
|
+
**Version: 1.0.0**
|
|
4
|
+
**Date: 10/14/2025**
|
|
5
|
+
**Author: Engineer Navid Rezadoost**
|
|
6
|
+
**TDR Document ID: [TDR-SVG-INTRGRATION-METHODS-001](https://docs.google.com/document/d/1b04_V01xOvLiSMzuPdaRynANlnt2wYdJ_vjs9MAqtn4/edit?tab=t.0)**
|
|
7
|
+
**Status**: Proposed
|
|
8
|
+
|
|
9
|
+
**Context**
|
|
10
|
+
This service is responsible for managing svg files. Given the documentation provided in the TDR for implementing Method 3, which covers the weaknesses of svgr, it was decided to release this package as an open source service on npm.
|
|
11
|
+
|
|
12
|
+
**Similar Weaknesses That We Are Looking To Solve In This Process**
|
|
13
|
+
|
|
14
|
+
* Add more commands for more control and mastery over svg file management
|
|
15
|
+
* Add different commands for rendering and rebuilding svg components with more control over files that we do not want to be rebuilt
|
|
16
|
+
* Add a command to create a component for new files that are added
|
|
17
|
+
* A command to componentize a specific svg
|
|
18
|
+
* Add settings for files that should remain unchanged due to specific styling
|
|
19
|
+
* Introduce the folder and run the build as \--watch as soon as a new svg file is added to the specified folder, the svg will be built automatically
|
|
20
|
+
* Create a config file or command on the command line to specify the source file to monitor or process and specify the destination directory
|
|
21
|
+
* Specify rules for building components in width and height dimensions and even styles that should be set as default
|
|
22
|
+
|
|
23
|
+
#### **Decision**
|
|
24
|
+
|
|
25
|
+
We will develop a custom SVG integration CLI and runtime service for React that:
|
|
26
|
+
|
|
27
|
+
* Watches directories for new SVG files.
|
|
28
|
+
* Generates React components automatically with flexible configuration.
|
|
29
|
+
* Allows selective rebuilds and fine-grained control over output styles and props.
|
|
30
|
+
|
|
31
|
+
#### **Rationale**
|
|
32
|
+
|
|
33
|
+
SVGR, while popular, has the following shortcomings:
|
|
34
|
+
|
|
35
|
+
* Lacks a flexible CLI API for selective component generation.
|
|
36
|
+
* No built-in `--watch` mode for automatic builds on new file additions.
|
|
37
|
+
* Limited support for default dimension and styling rules.
|
|
38
|
+
* Difficult to exclude or lock specific SVGs from rebuilds.
|
|
39
|
+
|
|
40
|
+
#### **Consequences**
|
|
41
|
+
|
|
42
|
+
* More control and automation for developers.
|
|
43
|
+
* Slightly increased setup complexity.
|
|
44
|
+
* Responsibility to maintain a custom build tool.
|
|
45
|
+
|
|
46
|
+
## **Example Configuration and Commands**
|
|
47
|
+
|
|
48
|
+
**Include examples so developers can easily visualize the usage.**
|
|
49
|
+
|
|
50
|
+
### Example `.svgconfig.json`
|
|
51
|
+
|
|
52
|
+
| { "source": "./src/assets/svg", "output": "./src/components/icons", "watch": true, "defaultWidth": "24", "defaultHeight": "24", "defaultFill": "currentColor", "exclude": \["logo.svg", "brand-icon.svg"\], "styleRules": { "fill": "inherit", "stroke": "none" }} |
|
|
53
|
+
| :---- |
|
|
54
|
+
|
|
55
|
+
**Commands**
|
|
56
|
+
|
|
57
|
+
**Build Command**
|
|
58
|
+
Builds React components from all SVG files in the specified source directory.
|
|
59
|
+
|
|
60
|
+
| svg-tool build \[options\] |
|
|
61
|
+
| :---- |
|
|
62
|
+
|
|
63
|
+
| svg-tool build \--src ./src/assets/svg \--out ./src/components/icons |
|
|
64
|
+
| :---- |
|
|
65
|
+
|
|
66
|
+
### **What It Does**
|
|
67
|
+
|
|
68
|
+
* Converts every `.svg` in the source folder to a React component.
|
|
69
|
+
* Applies rules from `.svgconfig.json` if present.
|
|
70
|
+
* Generates file names based on kebab-case or PascalCase (configurable).
|
|
71
|
+
|
|
72
|
+
**Watch Command**
|
|
73
|
+
Continuously watches the source directory for new or updated SVG files, and automatically builds them.
|
|
74
|
+
|
|
75
|
+
| svg-tool watch \[options\] |
|
|
76
|
+
| :---- |
|
|
77
|
+
|
|
78
|
+
| svg-tool watch \--src ./src/assets/svg \--out ./src/components/icons |
|
|
79
|
+
| :---- |
|
|
80
|
+
|
|
81
|
+
### **What It Does**
|
|
82
|
+
|
|
83
|
+
* Automatically rebuilds when an SVG file is added, updated, or removed.
|
|
84
|
+
* Skips locked SVG files.
|
|
85
|
+
* Ideal for active development environments.
|
|
86
|
+
|
|
87
|
+
## **Generate Command**
|
|
88
|
+
|
|
89
|
+
Converts a specific SVG file into a React component on demand.
|
|
90
|
+
|
|
91
|
+
| svg-tool generate \<svgFile\> \[options\] |
|
|
92
|
+
| :---- |
|
|
93
|
+
|
|
94
|
+
| svg-tool generate ./src/assets/svg/heart.svg \--out ./src/components/icons |
|
|
95
|
+
| :---- |
|
|
96
|
+
|
|
97
|
+
### **What It Does**
|
|
98
|
+
|
|
99
|
+
* Converts only the specified file.
|
|
100
|
+
* Ideal for adding individual icons to an existing collection.
|
|
101
|
+
|
|
102
|
+
## **Lock Command**
|
|
103
|
+
|
|
104
|
+
Locks one or more SVG files to prevent them from being rebuilt or overwritten during batch operations.
|
|
105
|
+
|
|
106
|
+
| svg-tool lock \<svgFile\> \[options\] |
|
|
107
|
+
| :---- |
|
|
108
|
+
|
|
109
|
+
| svg-tool lock ./src/assets/svg/logo.svg |
|
|
110
|
+
| :---- |
|
|
111
|
+
|
|
112
|
+
### **What It Does**
|
|
113
|
+
|
|
114
|
+
* Adds the specified file(s) to a `.svg-lock` or `.svgconfig.json` list.
|
|
115
|
+
* Protects specific SVGs with custom branding or styling.
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
## **Unlock Command**
|
|
119
|
+
|
|
120
|
+
Unlocks one or more SVG files previously marked as locked, allowing them to be rebuilt.
|
|
121
|
+
|
|
122
|
+
| svg-tool unlock \<svgFile\> \[options\] |
|
|
123
|
+
| :---- |
|
|
124
|
+
|
|
125
|
+
| svg-tool unlock ./src/assets/svg/logo.svg |
|
|
126
|
+
| :---- |
|
|
127
|
+
|
|
128
|
+
## **Config Command**
|
|
129
|
+
|
|
130
|
+
Creates or modifies a `.svgconfig.json` file with default settings for builds and watches.
|
|
131
|
+
|
|
132
|
+
| svg-tool config \[options\] |
|
|
133
|
+
| :---- |
|
|
134
|
+
|
|
135
|
+
| svg-tool config \--init |
|
|
136
|
+
| :---- |
|
|
137
|
+
|
|
138
|
+
**\--init**
|
|
139
|
+
|
|
140
|
+
| svg-tool config \--init |
|
|
141
|
+
| :---- |
|
|
142
|
+
|
|
143
|
+
**\--set \<key=value\>**
|
|
144
|
+
|
|
145
|
+
| svg-tool config \--set defaultWidth=32 |
|
|
146
|
+
| :---- |
|
|
147
|
+
|
|
148
|
+
**`--show`**
|
|
149
|
+
|
|
150
|
+
| svg-tool config \--show |
|
|
151
|
+
| :---- |
|
|
152
|
+
|
|
153
|
+
**`Full One-Line Command Closet (for Bash / Mac / Linux / PowerShell)`**
|
|
154
|
+
|
|
155
|
+
| svg-tool config \--init && svg-tool config \--set source=./src/assets/svg && svg-tool config \--set output=./src/components/icons && svg-tool config \--set watch=true && svg-tool config \--set defaultWidth=24 && svg-tool config \--set defaultHeight=24 && svg-tool config \--set defaultFill=currentColor && svg-tool lock ./src/assets/svg/logo.svg && svg-tool build \--src ./src/assets/svg \--out ./src/components/icons \--verbose && svg-tool generate ./src/assets/svg/new-icon.svg \--out ./src/components/icons && svg-tool unlock ./src/assets/svg/logo.svg && svg-tool watch \--src ./src/assets/svg \--out ./src/components/icons && svg-tool clean \--out ./src/components/icons |
|
|
156
|
+
| :---- |
|
|
157
|
+
|