{"id":22950,"library":"vite-svg-2-webfont","title":"vite-svg-2-webfont","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/atlowChemi/vite-svg-2-webfont","tags":["javascript","vite","vite-plugin","svg-font","webfont","webfont-loader","typescript"],"install":[{"cmd":"npm install vite-svg-2-webfont","lang":"bash","label":"npm"},{"cmd":"yarn add vite-svg-2-webfont","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-svg-2-webfont","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for plugin to function; version must be ^6.0.0, ^7.0.0, or ^8.0.0","package":"vite","optional":true},{"reason":"Internal Rust-based native module used for font generation; bundled but requires Node N-API support","package":"webfont-generator","optional":false}],"imports":[{"note":"Default export only. Named import will fail. ESM-only since v7; no CommonJS exports.","wrong":"import { viteSvgToWebfont } from 'vite-svg-2-webfont'","symbol":"viteSvgToWebfont","correct":"import viteSvgToWebfont from 'vite-svg-2-webfont'"},{"note":"Virtual module side-effect import; cannot be used as a default import. Only available during build when plugin is active.","wrong":"import style from 'virtual:vite-svg-2-webfont.css'","symbol":"virtual:vite-svg-2-webfont.css","correct":"import 'virtual:vite-svg-2-webfont.css'"},{"note":"TypeScript type, use 'import type'. Not a runtime value.","wrong":"import { ViteSvgToWebfontOptions } from 'vite-svg-2-webfont'","symbol":"ViteSvgToWebfontOptions","correct":"import type { ViteSvgToWebfontOptions } from 'vite-svg-2-webfont'"},{"note":"Package is ESM-only since v7; require() throws ERR_REQUIRE_ESM.","wrong":"const viteSvgToWebfont = require('vite-svg-2-webfont')","symbol":"require('vite-svg-2-webfont')","correct":"import viteSvgToWebfont from 'vite-svg-2-webfont'"}],"quickstart":{"code":"// vite.config.ts\nimport { resolve } from 'node:path';\nimport { defineConfig } from 'vite';\nimport viteSvgToWebfont from 'vite-svg-2-webfont';\n\nexport default defineConfig({\n  plugins: [\n    viteSvgToWebfont({\n      context: resolve(import.meta.dirname, 'icons'),\n      classPrefix: 'icon-',\n      baseSelector: 'icon',\n      formats: ['woff2', 'woff'],\n    }),\n  ],\n});\n\n// main.ts\nimport 'virtual:vite-svg-2-webfont.css';\n\n// index.html\n// <i class=\"icon icon-add\"></i>","lang":"typescript","description":"Configures the plugin to read SVG icons from an 'icons' folder, generates WOFF2/WOFF, and imports the virtual CSS."},"warnings":[{"fix":"Regenerate fonts after upgrading; font files from v6 are not binary-compatible with v7. Consider versioning font outputs.","message":"Generated font binaries differ at the byte level from v6.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Update custom cssContext callbacks to use the new single-argument signature. See migration guide.","message":"cssContext callback now receives a single argument; the second `options` and third `handlebars` parameters are removed.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Switch to `import` syntax or use dynamic import().","message":"Package is ESM-only since v7; `require()` usage will fail.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Avoid relying on preloadFormats in v6; use explicit <link rel=\"preload\"> instead.","message":"The `preloadFormats` option introduced in v6.1.0 may be removed or changed in the future.","severity":"deprecated","affected_versions":">=6.1.0 <7.0.0"},{"fix":"Upgrade Node.js to a supported version (20, 22, or 24+).","message":"The plugin requires Node.js version ^20 || ^22 || >=24. Older versions (e.g., 18, 23) will fail.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Mock the virtual module in test environments using vitest's `vi.mock` or Vite's `resolve.alias`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to `import viteSvgToWebfont from 'vite-svg-2-webfont'` or use dynamic `import()`.","cause":"Package is ESM-only since v7, but code uses CommonJS require().","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/vite-svg-2-webfont not supported."},{"fix":"Use `import viteSvgToWebfont from 'vite-svg-2-webfont'` (without curly braces).","cause":"Named import instead of default import.","error":"TypeError: viteSvgToWebfont is not a function"},{"fix":"Change cssContext from (tpl, options, handlebars) => ... to (singleArg) => ... where singleArg includes tpl.","cause":"Upgraded from v6 to v7 without updating the cssContext callback signature.","error":"Error: The `cssContext` callback now receives a single argument. The second `options` and third `handlebars` parameters are removed."},{"fix":"Ensure the directory exists and the path is correct (use `resolve()` with absolute path).","cause":"The `context` option points to a non-existent directory.","error":"Error: The font generation failed. 'context' directory does not exist: /path/to/icons"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}