tessl/npm-unplugin-icons

Access thousands of icons as components on-demand universally across multiple build tools and frameworks

—

Pending

Overview

Eval results

Files

Plugin Configuration

Name: tessl/npm-unplugin-icons
Author: tessl

Core plugin setup and configuration options for unplugin-icons across different build tools and frameworks.

Capabilities

Main Configuration Interface

The primary options interface for configuring unplugin-icons behavior.

/**
 * Main configuration options for unplugin-icons
 */
interface Options {
  /** Scale of icons against 1em (default: 1.2) */
  scale?: number;
  
  /** Style apply to icons by default (default: '') */
  defaultStyle?: string;
  
  /** Class names apply to icons by default (default: '') */
  defaultClass?: string;
  
  /** Loader for custom loaders */
  customCollections?: Record<string, CustomIconLoader | InlineCollection>;
  
  /** Icon customizer */
  iconCustomizer?: IconCustomizer;
  
  /** Current working directory for resolving collections from node_modules */
  collectionsNodeResolvePath?: string | string[];
  
  /** 
   * Transform raw SVG.
   * WARNING: transform will only be applied when using custom icon collection.
   */
  transform?: (svg: string, collection: string, icon: string) => Awaitable<string>;
  
  /** Auto install icon sources package when the usages is detected (default: false) */
  autoInstall?: boolean;
  
  /** Compiler (default: detect automatically, fallback to 'vue3') */
  compiler?: 'astro' | 'jsx' | 'marko' | 'none' | 'solid' | 'svelte' | 'raw' | 'vue2' | 'vue3' | 'web-components' | 'qwik' | CustomCompiler;
  
  /** JSX style, works only when compiler set to jsx (default: detect automatically, fallback to 'react') */
  jsx?: 'react' | 'preact' | 'qwik';
  
  /** Config for Web Components compiler */
  webComponents?: WebComponentsConfig;
}

Web Components Configuration

Configuration options specific to the web-components compiler.

/**
 * Configuration for Web Components compiler
 */
interface WebComponentsConfig {
  /** Call customElements.define automatically on module importing */
  autoDefine?: boolean;
  
  /** Prefix for auto defining (default: 'icon') */
  iconPrefix?: string;
  
  /** Use shadow DOM (default: false) */
  shadow?: boolean;
}

Configuration Type Definitions

Type definitions for configuration functions and custom implementations.

/**
 * Icon customizer function
 */
type IconCustomizer = (
  collection: string, 
  icon: string, 
  props: Record<string, string>
) => Awaitable<void>;

/**
 * Custom icon loader function
 */
type CustomIconLoader = (name: string) => Awaitable<string | undefined>;

/**
 * Inline collection definition
 */
type InlineCollection = Record<string, string | (() => Awaitable<string | undefined>)>;

/**
 * Custom compiler definition
 */
interface CustomCompiler {
  compiler: Awaitable<Compiler>;
  extension?: string;
}

/**
 * Compiler function signature
 */
type Compiler = (
  svg: string,
  collection: string,
  icon: string,
  options: ResolvedOptions
) => string | Promise<string>;

/**
 * Resolved configuration options
 */
type ResolvedOptions = Omit<Required<Options>, 'iconSource' | 'transform'> & Pick<Options, 'transform'>;

Usage Examples

Basic Configuration

import Icons from "unplugin-icons/vite";

export default {
  plugins: [
    Icons({
      scale: 1.5,
      defaultClass: "icon",
      compiler: "vue3",
      autoInstall: true,
    }),
  ],
};

Custom Collections

import Icons from "unplugin-icons/vite";
import { FileSystemIconLoader } from "unplugin-icons/loaders";

export default {
  plugins: [
    Icons({
      customCollections: {
        // Load from filesystem
        'my-icons': FileSystemIconLoader('./src/assets/icons', svg => 
          svg.replace(/^<svg /, '<svg fill="currentColor" ')
        ),
        
        // Inline collection
        'custom': {
          'star': '<svg>...</svg>',
          'heart': () => Promise.resolve('<svg>...</svg>'),
        }
      },
      iconCustomizer: (collection, icon, props) => {
        if (collection === 'my-icons') {
          props.class = `custom-icon ${props.class || ''}`.trim();
        }
      },
    }),
  ],
};

Framework-Specific Configuration

// React/JSX setup
Icons({
  compiler: "jsx",
  jsx: "react",
  defaultStyle: "display: inline-block;",
})

// Vue 3 setup
Icons({
  compiler: "vue3",
  defaultClass: "vue-icon",
})

// Svelte setup
Icons({
  compiler: "svelte",
  scale: 1.1,
})

// Web Components setup
Icons({
  compiler: "web-components",
  webComponents: {
    autoDefine: true,
    iconPrefix: "my-icon",
    shadow: true,
  },
})

Custom Compiler

import Icons from "unplugin-icons/vite";

export default {
  plugins: [
    Icons({
      compiler: {
        compiler: async (svg, collection, icon, options) => {
          // Custom compilation logic
          return `export default "${svg.replace(/"/g, '\\"')}"`;
        },
        extension: "js",
      },
    }),
  ],
};

Install with Tessl CLI