@hugeicons/core-free-icons 1.1.0 → 1.2.0

package/README.md

@@ -12,7 +12,8 @@ Hugeicons is a comprehensive icon library designed for modern web and mobile app
 - **4,500+ Free Icons**: Extensive collection of Stroke Rounded icons covering essential UI elements, actions, and concepts
 - **Pixel Perfect**: Every icon is crafted on a 24x24 pixel grid ensuring crisp, clear display at any size
 - **Customizable**: Easily adjust colors, sizes, and styles to match your design needs
-- **Optimized Loading**: New individual icon imports reduce bundle size by 99%
+- **Tree-Shakeable**: Optimized for modern bundlers with automatic dead code elimination
+- **Optimized Loading**: Individual icon imports reduce bundle size by 99%
 - **Regular Updates**: New icons added regularly to keep up with evolving design trends
 
 > 📚 **Looking for Pro Icons?** Check out our comprehensive documentation at [docs.hugeicons.com](https://docs.hugeicons.com) for detailed information about pro icons, styles, and advanced usage.
@@ -59,7 +60,7 @@ Loads the entire icon library (use when you need many icons dynamically):
 const { Home01Icon } = await import('@hugeicons/core-free-icons');
 ```
 
-#### 3. Dynamic Import - Individual Icons (NEW ✨)
+#### 3. Dynamic Import - Individual Icons
 Loads only the specific icon you need (99% smaller bundle size):
 
 ```javascript
@@ -68,24 +69,152 @@ const icon = await import('@hugeicons/core-free-icons/Home01Icon');
 const Home01Icon = icon.default;
 ```
 
+#### 4. Dynamic Loader Functions (NEW ✨ Recommended)
+The most efficient way to load icons dynamically with built-in caching:
+
+```javascript
+import { loadIcon, loadIcons } from '@hugeicons/core-free-icons/loader';
+
+// Load single icon
+const homeIcon = await loadIcon('Home01Icon');
+
+// Load multiple icons (parallel loading)
+const icons = await loadIcons(['Calendar01Icon', 'UserIcon', 'SearchIcon']);
+
+// Check if icon exists
+const exists = await iconExists('Home01Icon'); // true
+```
+
+**Loader Benefits:**
+- ✅ **Automatic Caching** - Icons are cached after first load
+- ✅ **TypeScript Support** - Full type definitions included
+- ✅ **On-Demand Loading** - Only loads what you request
+- ✅ **Parallel Loading** - `loadIcons` loads multiple icons simultaneously
+- ✅ **Error Handling** - Clear error messages for missing icons
+- ✅ **Zero Vite Overhead** - No dev server slowdown
+
+**React Example with Loader:**
+```jsx
+import { useState, useEffect } from 'react';
+import { loadIcon } from '@hugeicons/core-free-icons/loader';
+import { HugeiconsIcon } from '@hugeicons/react';
+
+function DynamicIcon({ iconName }) {
+  const [icon, setIcon] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    loadIcon(iconName)
+      .then(setIcon)
+      .catch(console.error)
+      .finally(() => setLoading(false));
+  }, [iconName]);
+
+  if (loading) return <div>Loading...</div>;
+  if (!icon) return <div>Icon not found</div>;
+
+  return <HugeiconsIcon icon={icon} size={24} />;
+}
+```
+
 ### Performance Comparison
 
-| Import Method | Bundle Size | Load Time | Best For |
-|--------------|-------------|-----------|----------|
-| Static Import | ~2-3KB per icon | 0ms (bundled) | Production builds |
-| Dynamic Full Bundle | ~5MB | 100-200ms | Many dynamic icons |
-| Dynamic Individual | ~0.75KB | 10-20ms | Icon pickers, lazy loading |
+| Import Method | Bundle Size | Load Time | Caching | Best For |
+|--------------|-------------|-----------|---------|----------|
+| Static Import | ~2-3KB per icon | 0ms (bundled) | N/A | Production builds |
+| Dynamic Full Bundle | ~5MB | 100-200ms | No | Many dynamic icons |
+| Dynamic Individual | ~0.75KB | 10-20ms | No | Icon pickers, lazy loading |
+| **Loader Functions** ⭐ | **~2KB + 0.75KB per icon** | **8-20ms** | **Yes** | **Dynamic apps, CMS, config-driven UIs** |
 
 For real-world applications, we recommend using our framework-specific packages that provide optimized components and additional features. Check out the Framework Support section below for more details.
 
+## Loader API Reference
+
+The loader provides a complete API for dynamic icon management:
+
+### Available Functions
+
+```typescript
+// Load single icon with caching
+loadIcon(iconName: string): Promise<IconSvgObject>
+
+// Load multiple icons in parallel
+loadIcons(iconNames: string[]): Promise<IconSvgObject[]>
+
+// Check if an icon exists
+iconExists(iconName: string): Promise<boolean>
+
+// Clear icon cache
+clearIconCache(): void
+
+// Get cache size
+getCacheSize(): number
+
+// Style-specific aliases (for multi-package usage)
+loadIconFreeIcons(iconName: string): Promise<IconSvgObject>
+loadIconsFreeIcons(iconNames: string[]): Promise<IconSvgObject[]>
+```
+
+### Complete Usage Example
+
+```javascript
+import { 
+  loadIcon, 
+  loadIcons, 
+  iconExists,
+  clearIconCache,
+  getCacheSize
+} from '@hugeicons/core-free-icons/loader';
+
+// Load single icon
+const home = await loadIcon('Home01Icon');
+console.log('Loaded:', home); // Array of SVG path data
+
+// Load multiple icons
+const [calendar, user, search] = await loadIcons([
+  'Calendar01Icon',
+  'UserIcon', 
+  'Search01Icon'
+]);
+
+// Check existence before loading
+if (await iconExists('Rocket01Icon')) {
+  const rocket = await loadIcon('Rocket01Icon');
+}
+
+// Cache management
+console.log('Cached icons:', getCacheSize()); // 4
+clearIconCache();
+console.log('After clear:', getCacheSize()); // 0
+```
+
+## Tree-Shaking Support
+
+This package is optimized for tree-shaking with modern bundlers (Webpack, Rollup, Vite, etc.). When you import icons using the standard syntax, bundlers will automatically eliminate unused icons:
+
+```javascript
+// Only the icons you import will be included in your bundle
+import { UserIcon, HomeIcon } from '@hugeicons/core-free-icons';
+
+// Bundlers automatically tree-shake unused icons
+// Result: Only UserIcon and HomeIcon (~1.5KB) instead of entire library (~5MB)
+```
+
+**Requirements for tree-shaking:**
+- Use a modern bundler (Webpack 5+, Rollup, Vite, Parcel)
+- Ensure your bundler has tree-shaking enabled
+- The package automatically sets `sideEffects: false` for optimal tree-shaking
+
 ## Features
 
+- ⭐ **Dynamic Loader Functions**: NEW! Load icons on-demand with automatic caching
 - 🎯 **Individual Icon Imports**: Load only what you need with 99% bundle size reduction
 - 🌳 **Tree-shakeable**: Optimized for modern bundlers
-- 📦 **Multiple Import Methods**: Static, dynamic bundle, or dynamic individual
+- 📦 **Multiple Import Methods**: Static, dynamic bundle, dynamic individual, or loader
 - 🔷 **TypeScript Support**: Full type definitions included
 - 📱 **Framework Agnostic**: Works with any JavaScript framework
 - ⚡ **Optimized Performance**: Lazy load icons on demand
+- 💾 **Built-in Caching**: In-memory cache for faster subsequent loads
 - 🎨 **Customizable**: Easy to style with CSS or inline styles
 - ✅ **ESM & CommonJS**: Support for both module systems
 - 🚀 **Zero Dependencies**: No external dependencies

package/dist/cjs/index.js

@@ -29114,6 +29114,94 @@ const ZzzIcon = /*#__PURE__*/ [
   ["path", { d: "M14 9H20L14 15H20", stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: "1.5", key: "2" }]
 ];
 
+/**
+ * Dynamic Icon Loader
+ * 
+ * Load icons dynamically by name without importing all icons upfront.
+ * This is perfect for applications that need to load icons based on
+ * user data, CMS content, or configuration files.
+ * 
+ * @example
+ * import { loadIcon } from '@hugeicons/core-free-icons/loader';
+ * 
+ * const icon = await loadIcon('Home01Icon');
+ * // Use icon with @hugeicons/react or any other renderer
+ */
+
+// In-memory cache for loaded icons
+const iconCache = new Map();
+
+/**
+ * Load a single icon by name
+ * @param iconName - The name of the icon (e.g., 'Home01Icon', 'Calendar01Icon')
+ * @returns Promise resolving to the icon data
+ * @throws Error if icon not found
+ */
+async function loadIcon(iconName) {
+  // Check cache first
+  if (iconCache.has(iconName)) {
+    return iconCache.get(iconName);
+  }
+
+  try {
+    // Dynamic import - pre-built by rollup, no overhead in dev!
+    // @vite-ignore tells Vite to skip static analysis
+    const module = await import(/* @vite-ignore */ `./${iconName}.js`);
+    const iconData = module.default ;
+    
+    if (!iconData) {
+      throw new Error(`Icon data not found for "${iconName}"`);
+    }
+    
+    // Cache the loaded icon
+    iconCache.set(iconName, iconData);
+    
+    return iconData;
+  } catch (error) {
+    throw new Error(
+      `Failed to load icon "${iconName}". Make sure the icon exists in this package. Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Load multiple icons at once
+ * @param iconNames - Array of icon names to load
+ * @returns Promise resolving to array of icon data in the same order
+ */
+async function loadIcons(iconNames) {
+  return Promise.all(iconNames.map(name => loadIcon(name)));
+}
+
+/**
+ * Check if an icon exists without loading it
+ * @param iconName - The name of the icon to check
+ * @returns Promise resolving to true if icon exists, false otherwise
+ */
+async function iconExists(iconName) {
+  try {
+    await loadIcon(iconName);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Clear the icon cache
+ * Useful for memory management in long-running applications
+ */
+function clearIconCache() {
+  iconCache.clear();
+}
+
+/**
+ * Get the number of cached icons
+ */
+function getCacheSize() {
+  return iconCache.size;
+}
+
 exports.AbacusFreeIcons = AbacusIcon;
 exports.AbacusIcon = AbacusIcon;
 exports.AbsoluteFreeIcons = AbsoluteIcon;
@@ -39605,5 +39693,10 @@ exports.ZshFreeIcons = ZshIcon;
 exports.ZshIcon = ZshIcon;
 exports.ZzzFreeIcons = ZzzIcon;
 exports.ZzzIcon = ZzzIcon;
+exports.clearIconCache = clearIconCache;
+exports.getCacheSize = getCacheSize;
+exports.iconExists = iconExists;
 exports.jarIconFreeIcons = IconjarIcon;
+exports.loadIcon = loadIcon;
+exports.loadIcons = loadIcons;
 //# sourceMappingURL=index.js.map