vite-plugin-fantasticon

1.4.1 verified Mon Apr 27 auth: no javascript

Vite plugin to build icon fonts from SVG files using fantasticon. Current stable version 1.4.1, released sporadically. Supports single and multiple icon fonts with HMR via virtual imports. Generates CSS, TS constants, JSON metadata, and HTML preview. Differentiators: zero-config defaults, TypeScript types included, and built-in HMR for font assets.

Common errors

error ERR_REQUIRE_ESM ↓

cause Using require() to import ESM-only module.

fix

Change to import statement: import fantasticon from 'vite-plugin-fantasticon'.

error ENOENT: no such file or directory, open 'icons/icons/...' ↓

cause Default inputDir appends 'icons/{name}' when name is set to something other than 'icons', leading to double nesting.

fix

Set inputDir explicitly: fantasticon({ inputDir: 'my-icons' }).

error Failed to resolve import "fontasticon:icons" ↓

cause Plugin is not loaded or the virtual import prefix does not match the configured font name.

fix

Ensure plugin is added in vite config and use exact font name: import 'fontasticon:<font-name>'.

Warnings

gotcha HMR virtual import must use 'fontasticon:' prefix exactly as configured font name. ↓

fix Use import 'fontasticon:icons' if font name is 'icons'.

gotcha Default inputDir depends on font name: if name is not 'icons', it becomes 'icons/{name}'. This can cause missing files if directories are not named accordingly. ↓

fix Explicitly set inputDir in options to avoid confusion.

gotcha Plugin is ESM-only; using require() will fail at runtime with 'ERR_REQUIRE_ESM'. ↓

fix Use import syntax; set type: 'module' in package.json if needed.

deprecated No breaking changes reported, but TypeScript types may not cover all fantasticon options. ↓

fix Use // @ts-ignore if needed, or contribute types upstream.

Install

npm install vite-plugin-fantasticon

yarn add vite-plugin-fantasticon

pnpm add vite-plugin-fantasticon

Imports

default

wrong

const fantasticon = require('vite-plugin-fantasticon')

correct

import fantasticon from 'vite-plugin-fantasticon'

CommonJS require() fails because plugin is ESM-only.

defaults
```
import { defaults } from 'vite-plugin-fantasticon'
```
Utility to get default options; not needed for basic usage.
Virtual import
wrong
```
import 'virtual:fantasticon'
```
correct
```
import 'fontasticon:icons'
```
Must use 'fontasticon:' prefix with your font name, not 'virtual:'.

Quickstart

Shows minimal Vite config with fantasticon plugin and HMR import for icon font.

// vite.config.ts
import { defineConfig } from 'vite';
import fantasticon from 'vite-plugin-fantasticon';

export default defineConfig({
  plugins: [
    fantasticon({
      name: 'icons',
      inputDir: 'icons',
      outputDir: './dist',
      fontTypes: ['woff2', 'woff'],
      assetTypes: ['css', 'ts', 'json'],
    }),
  ],
});

// In a source file to enable HMR:
import 'fontasticon:icons';