vite-svg-2-webfont

7.0.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that generates webfonts (WOFF2, WOFF, TTF, EOT) from SVG icon files at build time. Current stable version is 7.0.0, released April 2026 with a major breaking change: the internal generator was rewritten from @vusion/webfonts-generator to a native Rust core, changing font binary output and the cssContext callback signature. The plugin exposes a virtual CSS module that can be imported directly into your app, supporting class-based icon usage. It requires Vite ^6.0.0 || ^7.0.0 || ^8.0.0 and Node ^20 || ^22 || >=24. Differentiators: tight Vite integration, zero-config setup, and high-performance Rust-based generation compared to slower Node.js alternatives.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/vite-svg-2-webfont not supported. ↓

cause Package is ESM-only since v7, but code uses CommonJS require().

fix

Change to import viteSvgToWebfont from 'vite-svg-2-webfont' or use dynamic import().

error TypeError: viteSvgToWebfont is not a function ↓

cause Named import instead of default import.

fix

Use import viteSvgToWebfont from 'vite-svg-2-webfont' (without curly braces).

error Error: The `cssContext` callback now receives a single argument. The second `options` and third `handlebars` parameters are removed. ↓

cause Upgraded from v6 to v7 without updating the cssContext callback signature.

fix

Change cssContext from (tpl, options, handlebars) => ... to (singleArg) => ... where singleArg includes tpl.

error Error: The font generation failed. 'context' directory does not exist: /path/to/icons ↓

cause The `context` option points to a non-existent directory.

fix

Ensure the directory exists and the path is correct (use resolve() with absolute path).

Warnings

breaking Generated font binaries differ at the byte level from v6. ↓

fix Regenerate fonts after upgrading; font files from v6 are not binary-compatible with v7. Consider versioning font outputs.

breaking cssContext callback now receives a single argument; the second `options` and third `handlebars` parameters are removed. ↓

fix Update custom cssContext callbacks to use the new single-argument signature. See migration guide.

breaking Package is ESM-only since v7; `require()` usage will fail. ↓

fix Switch to `import` syntax or use dynamic import().

deprecated The `preloadFormats` option introduced in v6.1.0 may be removed or changed in the future. ↓

fix Avoid relying on preloadFormats in v6; use explicit <link rel="preload"> instead.

gotcha The plugin requires Node.js version ^20 || ^22 || >=24. Older versions (e.g., 18, 23) will fail. ↓

fix Upgrade Node.js to a supported version (20, 22, or 24+).

gotcha Virtual CSS module `virtual:vite-svg-2-webfont.css` is only available during build. Importing it outside a Vite context (e.g., in tests) will fail. ↓

fix Mock the virtual module in test environments using vitest's `vi.mock` or Vite's `resolve.alias`.

Install

npm install vite-svg-2-webfont

yarn add vite-svg-2-webfont

pnpm add vite-svg-2-webfont

Imports

viteSvgToWebfont
wrong
```
import { viteSvgToWebfont } from 'vite-svg-2-webfont'
```
correct
```
import viteSvgToWebfont from 'vite-svg-2-webfont'
```
Default export only. Named import will fail. ESM-only since v7; no CommonJS exports.
virtual:vite-svg-2-webfont.css
wrong
```
import style from 'virtual:vite-svg-2-webfont.css'
```
correct
```
import 'virtual:vite-svg-2-webfont.css'
```
Virtual module side-effect import; cannot be used as a default import. Only available during build when plugin is active.

ViteSvgToWebfontOptions

wrong

import { ViteSvgToWebfontOptions } from 'vite-svg-2-webfont'

correct

import type { ViteSvgToWebfontOptions } from 'vite-svg-2-webfont'

TypeScript type, use 'import type'. Not a runtime value.

require('vite-svg-2-webfont')

wrong

const viteSvgToWebfont = require('vite-svg-2-webfont')

correct

import viteSvgToWebfont from 'vite-svg-2-webfont'

Package is ESM-only since v7; require() throws ERR_REQUIRE_ESM.

Quickstart

Configures the plugin to read SVG icons from an 'icons' folder, generates WOFF2/WOFF, and imports the virtual CSS.

// vite.config.ts
import { resolve } from 'node:path';
import { defineConfig } from 'vite';
import viteSvgToWebfont from 'vite-svg-2-webfont';

export default defineConfig({
  plugins: [
    viteSvgToWebfont({
      context: resolve(import.meta.dirname, 'icons'),
      classPrefix: 'icon-',
      baseSelector: 'icon',
      formats: ['woff2', 'woff'],
    }),
  ],
});

// main.ts
import 'virtual:vite-svg-2-webfont.css';

// index.html
// <i class="icon icon-add"></i>