vectify 2.1.0 → 2.1.2

package/README.md

@@ -116,7 +116,7 @@ src/icons/
 ### 4. Use in Your Code
 
 ```tsx
-import { ArrowRight, User, Settings } from './icons'
+import { ArrowRight, Settings, User } from './icons'
 
 function App() {
   return (
@@ -153,6 +153,7 @@ npx vectify generate [options]
 Options:
   -c, --config    Path to config file (default: vectify.config.ts)
   --dry-run       Preview what will be generated without writing files
+  --force         Force full regeneration, ignoring cache
 ```
 
 ### `vectify watch`
@@ -187,6 +188,7 @@ All available options for `defineConfig()` are documented in the tables below.
 | `suffix` | `string` | `''` | ❌ | Suffix added to all component names. | `suffix: 'Icon'` → `ArrowRightIcon` |
 | `transform` | `(name: string) => string` | - | ❌ | Custom function to transform SVG filename to component name. Overrides default PascalCase conversion and prefix/suffix. | `transform: (n) => 'X' + n` |
 | `format` | `boolean` \| `'prettier'` \| `'eslint'` \| `'biome'` \| `FormatConfig` | `false` | ❌ | Auto-format generated files after generation. See [Auto Formatting](#auto-formatting) for details. | `format: true` |
+| `incremental` | `object` | `{ enabled: true }` | ❌ | Incremental generation configuration. Enables content-based caching for faster regeneration. See [Incremental Generation](#incremental-generation) for details. | `incremental: { enabled: true, cacheDir: '.vectify' }` |
 
 #### `generateOptions` Object
 
@@ -197,6 +199,45 @@ All available options for `defineConfig()` are documented in the tables below.
 | `preview` | `boolean` | `false` | Generate interactive `preview.html` for browsing all icons locally. Useful for design review. | `preview: true` |
 | `cleanOutput` | `boolean` | `false` | Remove orphaned component files that no longer have corresponding SVG files. Helps keep output directory clean. | `cleanOutput: true` |
 
+#### `incremental` Object
+
+Incremental generation uses content-based caching to dramatically speed up regeneration when only a few files change. This is especially beneficial for large icon sets (100+ icons).
+
+| Parameter | Type | Default | Description | Example |
+|-----------|------|---------|-------------|----------|
+| `enabled` | `boolean` | `true` | Enable incremental generation with content-based caching. When enabled, only changed files are regenerated. | `enabled: true` |
+| `cacheDir` | `string` | `'.vectify'` | Directory name for cache storage (relative to output directory). Cache is stored as `<output>/<cacheDir>/cache.json`. | `cacheDir: '.vectify'` |
+
+**How it works:**
+- Uses SHA-256 content hashing to detect real file changes (not just modification time)
+- Automatically invalidates cache when configuration changes
+- Provides 10-50x performance improvement for single file changes in large icon sets
+- Cache is transparent and requires no manual management
+
+**Performance:**
+- First generation: Same speed as before (no cache)
+- Subsequent generations with no changes: ~95% cache hit rate, 10-50x faster
+- Single file change: Only regenerates changed file + index file
+- Configuration change: Automatic full regeneration
+
+**Disabling incremental generation:**
+```typescript
+export default defineConfig({
+  framework: 'react',
+  input: './icons',
+  output: './src/icons',
+  incremental: {
+    enabled: false, // Disable caching
+  },
+})
+```
+
+**Force full regeneration:**
+```bash
+# Bypass cache and regenerate all icons
+npx vectify generate --force
+```
+
 #### Auto Formatting
 
 Vectify can automatically format generated files using your project's formatter. This ensures generated code matches your project's code style.
@@ -235,7 +276,7 @@ When `format: true`, Vectify looks for config files in this order:
 ```typescript
 export default defineConfig({
   format: {
-    tool: 'prettier',      // 'auto' | 'prettier' | 'eslint' | 'biome'
+    tool: 'prettier', // 'auto' | 'prettier' | 'eslint' | 'biome'
     args: '--single-quote', // Additional CLI arguments
   },
 })
@@ -269,6 +310,8 @@ format: false
 | `enabled` | `boolean` | `false` | Enable watch mode. Automatically regenerate components when SVG files are added, modified, or deleted in the input directory. | `enabled: true` |
 | `ignore` | `string[]` | - | Array of glob patterns to ignore during watch. | `ignore: ['**/node_modules/**', '**/.git/**']` |
 | `debounce` | `number` | `300` | Debounce delay in milliseconds before triggering regeneration. Prevents excessive rebuilds. | `debounce: 500` |
+| `minFileSize` | `number` | `20` | Minimum valid SVG file size in bytes. Files smaller than this are considered empty and will be retried. | `minFileSize: 20` |
+| `emptyFileRetryDelay` | `number` | `2000` | Delay in milliseconds before retrying empty SVG files. Allows time for content to be pasted. | `emptyFileRetryDelay: 2000` |
 
 #### `svgoConfig` Object
 
@@ -357,7 +400,7 @@ export default defineConfig({
   hooks: {
     beforeParse: (svg, fileName) => {
       // Replace black with currentColor for customization
-      return svg.replace(/#000000/gi, 'currentColor')
+      return svg.replace(/#000000/g, 'currentColor')
     },
     afterGenerate: (code, iconName) => {
       // Add JSDoc comment to each component
@@ -393,7 +436,6 @@ The index file automatically uses the correct export style for your chosen frame
 - `keepColors: false` - Best for single-color icons that should inherit text color. Uses `currentColor` and allows runtime customization via the `color` prop.
 - `keepColors: true` - Best for multi-color brand icons. Preserves original SVG fill/stroke colors.
 
-
 ## Component Props
 
 All generated components accept the following props:
@@ -401,19 +443,19 @@ All generated components accept the following props:
 ```typescript
 interface IconProps {
   // Icon size (default: 24)
-  size?: number | string
+  'size'?: number | string
 
   // Icon color (default: 'currentColor')
-  color?: string
+  'color'?: string
 
   // Stroke width for stroke-based icons (default: 2)
-  strokeWidth?: number | string
+  'strokeWidth'?: number | string
 
   // CSS class name
-  className?: string
+  'className'?: string
 
   // Accessibility: icon title
-  title?: string
+  'title'?: string
 
   // Accessibility: aria-label
   'aria-label'?: string
@@ -553,10 +595,10 @@ document.getElementById('app').appendChild(icon)
 
 ```typescript
 // For single-color icons (default)
-keepColors: false  // Uses currentColor, customizable via color prop
+keepColors: false // Uses currentColor, customizable via color prop
 
 // For multi-color icons
-keepColors: true   // Preserves original colors from SVG
+keepColors: true // Preserves original colors from SVG
 ```
 
 ### 4. Project Structure
@@ -696,10 +738,10 @@ export default defineConfig({
 ```tsx
 // Before
 import { FiArrowRight } from 'react-icons/fi'
-<FiArrowRight size={24} />
 
 // After
 import { ArrowRight } from './icons'
+<FiArrowRight size={24} />
 <ArrowRight size={24} />
 ```
 
@@ -708,10 +750,10 @@ import { ArrowRight } from './icons'
 ```tsx
 // Before
 import { Icon } from '@iconify/react'
-<Icon icon="mdi:arrow-right" />
 
 // After
 import { ArrowRight } from './icons'
+<Icon icon="mdi:arrow-right" />
 <ArrowRight />
 ```
 

package/README.zh-CN.md

@@ -116,7 +116,7 @@ src/icons/
 ### 4. 在代码中使用
 
 ```tsx
-import { ArrowRight, User, Settings } from './icons'
+import { ArrowRight, Settings, User } from './icons'
 
 function App() {
   return (
@@ -153,6 +153,7 @@ npx vectify generate [选项]
 选项:
   -c, --config    配置文件路径 (默认: vectify.config.ts)
   --dry-run       预览将要生成的内容而不实际写入文件
+  --force         强制完全重新生成，忽略缓存
 ```
 
 ### `vectify watch`
@@ -187,6 +188,7 @@ npx vectify watch [选项]
 | `suffix` | `string` | `''` | ❌ | 添加到所有组件名称后的后缀 | `suffix: 'Icon'` → `ArrowRightIcon` |
 | `transform` | `(name: string) => string` | - | ❌ | 自定义函数，将 SVG 文件名转换为组件名。覆盖默认的 PascalCase 转换和 prefix/suffix | `transform: (n) => 'X' + n` |
 | `format` | `boolean` \| `'prettier'` \| `'eslint'` \| `'biome'` \| `FormatConfig` | `false` | ❌ | 生成后自动格式化文件。详见 [自动格式化](#自动格式化) | `format: true` |
+| `incremental` | `object` | `{ enabled: true }` | ❌ | 增量生成配置。启用基于内容的缓存以加快重新生成速度。详见 [增量生成](#增量生成) | `incremental: { enabled: true, cacheDir: '.vectify' }` |
 
 #### `generateOptions` 对象
 
@@ -197,6 +199,45 @@ npx vectify watch [选项]
 | `preview` | `boolean` | `false` | 生成交互式 `preview.html` 用于本地浏览所有图标。适合设计审查 | `preview: true` |
 | `cleanOutput` | `boolean` | `false` | 移除不再有对应 SVG 文件的孤立组件。帮助保持输出目录整洁 | `cleanOutput: true` |
 
+#### `incremental` 对象
+
+增量生成使用基于内容的缓存来显著加快重新生成速度，特别适合大型图标集（100+ 图标）。
+
+| 参数 | 类型 | 默认值 | 说明 | 示例 |
+|------|------|--------|------|------|
+| `enabled` | `boolean` | `true` | 启用基于内容缓存的增量生成。启用后，只会重新生成变化的文件 | `enabled: true` |
+| `cacheDir` | `string` | `'.vectify'` | 缓存存储目录名（相对于输出目录）。缓存存储为 `<output>/<cacheDir>/cache.json` | `cacheDir: '.vectify'` |
+
+**工作原理：**
+- 使用 SHA-256 内容哈希检测真实文件变化（而非仅修改时间）
+- 配置变更时自动失效缓存
+- 对于大型图标集的单文件变更，提供 10-50 倍性能提升
+- 缓存是透明的，无需手动管理
+
+**性能表现：**
+- 首次生成：与之前速度相同（无缓存）
+- 无变更的后续生成：约 95% 缓存命中率，快 10-50 倍
+- 单文件变更：仅重新生成变化的文件 + 索引文件
+- 配置变更：自动完全重新生成
+
+**禁用增量生成：**
+```typescript
+export default defineConfig({
+  framework: 'react',
+  input: './icons',
+  output: './src/icons',
+  incremental: {
+    enabled: false, // 禁用缓存
+  },
+})
+```
+
+**强制完全重新生成：**
+```bash
+# 绕过缓存并重新生成所有图标
+npx vectify generate --force
+```
+
 #### 自动格式化
 
 Vectify 可以使用项目中的格式化工具自动格式化生成的文件。确保生成的代码符合项目的代码风格。
@@ -235,7 +276,7 @@ export default defineConfig({
 ```typescript
 export default defineConfig({
   format: {
-    tool: 'prettier',       // 'auto' | 'prettier' | 'eslint' | 'biome'
+    tool: 'prettier', // 'auto' | 'prettier' | 'eslint' | 'biome'
     args: '--single-quote', // 额外的 CLI 参数
   },
 })
@@ -269,6 +310,8 @@ format: false
 | `enabled` | `boolean` | `false` | 启用监听模式。在输入目录中添加、修改或删除 SVG 文件时自动重新生成组件 | `enabled: true` |
 | `ignore` | `string[]` | - | 监听时忽略的 glob 模式数组 | `ignore: ['**/node_modules/**', '**/.git/**']` |
 | `debounce` | `number` | `300` | 触发重新生成前的防抖延迟（毫秒）。防止过度重新构建 | `debounce: 500` |
+| `minFileSize` | `number` | `20` | 最小有效 SVG 文件大小（字节）。小于此大小的文件被视为空文件并将重试 | `minFileSize: 20` |
+| `emptyFileRetryDelay` | `number` | `2000` | 重试空 SVG 文件前的延迟（毫秒）。允许时间粘贴内容 | `emptyFileRetryDelay: 2000` |
 
 #### `svgoConfig` 对象
 
@@ -357,7 +400,7 @@ export default defineConfig({
   hooks: {
     beforeParse: (svg, fileName) => {
       // 将黑色替换为 currentColor 以便自定义
-      return svg.replace(/#000000/gi, 'currentColor')
+      return svg.replace(/#000000/g, 'currentColor')
     },
     afterGenerate: (code, iconName) => {
       // 为每个组件添加 JSDoc 注释
@@ -393,7 +436,6 @@ export default defineConfig({
 - `keepColors: false` - 适合应继承文本颜色的单色图标。使用 `currentColor` 并允许通过 `color` 属性进行运行时自定义。
 - `keepColors: true` - 适合多色品牌图标。保留原始 SVG 的 fill/stroke 颜色。
 
-
 ## 🎨 组件属性
 
 所有生成的组件都接受以下属性：
@@ -401,19 +443,19 @@ export default defineConfig({
 ```typescript
 interface IconProps {
   // 图标大小 (默认: 24)
-  size?: number | string
+  'size'?: number | string
 
   // 图标颜色 (默认: 'currentColor')
-  color?: string
+  'color'?: string
 
   // 描边图标的描边宽度 (默认: 2)
-  strokeWidth?: number | string
+  'strokeWidth'?: number | string
 
   // CSS 类名
-  className?: string
+  'className'?: string
 
   // 无障碍：图标标题
-  title?: string
+  'title'?: string
 
   // 无障碍：aria-label
   'aria-label'?: string
@@ -553,10 +595,10 @@ document.getElementById('app').appendChild(icon)
 
 ```typescript
 // 单色图标（默认）
-keepColors: false  // 使用 currentColor，可通过 color 属性自定义
+keepColors: false // 使用 currentColor，可通过 color 属性自定义
 
 // 多色图标
-keepColors: true   // 保留 SVG 中的原始颜色
+keepColors: true // 保留 SVG 中的原始颜色
 ```
 
 ### 4. 项目结构
@@ -696,10 +738,10 @@ export default defineConfig({
 ```tsx
 // 之前
 import { FiArrowRight } from 'react-icons/fi'
-<FiArrowRight size={24} />
 
 // 之后
 import { ArrowRight } from './icons'
+<FiArrowRight size={24} />
 <ArrowRight size={24} />
 ```
 
@@ -708,10 +750,10 @@ import { ArrowRight } from './icons'
 ```tsx
 // 之前
 import { Icon } from '@iconify/react'
-<Icon icon="mdi:arrow-right" />
 
 // 之后
 import { ArrowRight } from './icons'
+<Icon icon="mdi:arrow-right" />
 <ArrowRight />
 ```