{"id":22671,"library":"vite-plugin-font","title":"vite-plugin-font","description":"A Vite plugin and family of bundler plugins (Vite, Nuxt, Next.js, Webpack, Rspack) for automatic web font optimization and CJK font splitting. Version 5.1.2 (stable, with recent releases up to 7.6.8 on the underlying cn-font-split engine). Powered by Rust-native cn-font-split for 50% faster builds. Key differentiators: per-project character subsetting for first-screen optimization, automatic WOFF2 conversion, CSS-only approach (no runtime JS), and built-in CLS offset reduction. Supports both full-scale and extremely lightweight optimization modes, with tree-shakeable font info exports. Actively maintained by the Chinese WebFont Project.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/KonghaYao/cn-font-split#release","tags":["javascript","vite","vite-plugin","nuxt","nuxt-plugin","next","next-plugin","webpack","webpack-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-font","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-font","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-font","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core font-splitting engine; Rust-native performance","package":"cn-font-split","optional":false}],"imports":[{"note":"Plugin is ESM-only; CommonJS require will fail.","wrong":"const Font = require('vite-plugin-font')","symbol":"default","correct":"import Font from 'vite-plugin-font'"},{"note":"Default export is a function; access .vite() method.","wrong":"import { vite } from 'vite-plugin-font'","symbol":"viteFont","correct":"import viteFont from 'vite-plugin-font'"},{"note":"Since v5, you must call .vite() for Vite config, not the default function directly.","wrong":"Font()","symbol":"Font.vite()","correct":"Font.vite()"},{"note":"Font files are treated as modules exporting css (with family, url, etc.) and fontFamilyFallback string. Do not import as raw asset.","wrong":"import font from './font.ttf'","symbol":"css / fontFamilyFallback","correct":"import { css, fontFamilyFallback } from './font.ttf';"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite';\nimport Font from 'vite-plugin-font';\n\nexport default defineConfig({\n  plugins: [Font.vite()],\n});\n\n// Then in your component:\nimport { css, fontFamilyFallback } from './public/SmileySans-Oblique.ttf';\ndocument.body.style.fontFamily = `\"${css.family}\", ${fontFamilyFallback}`;","lang":"javascript","description":"Basic setup for Vite: install plugin, add to config, then import font file as module to get CSS properties and fallback."},"warnings":[{"fix":"Use `Font.vite()` (or `Font.webpack()` for Webpack).","message":"Since v5, the default export is a function; you must call `Font.vite()` instead of `Font()`. Using `Font()` will throw `TypeError: Font is not a constructor`.","severity":"breaking","affected_versions":">=5.0"},{"fix":"Upgrade to Node.js 18 or later.","message":"Removed support for Node.js <18 in v7.","severity":"breaking","affected_versions":">=7.0"},{"fix":"Use `import { css } from '...'` and access `css.family`.","message":"The `family` export from font imports is deprecated in favor of `css.family`.","severity":"deprecated","affected_versions":">=5.1"},{"fix":"Destructure: `import { css, fontFamilyFallback } from './font.ttf'`.","message":"Font file imports return an object with `css` and `fontFamilyFallback`. Direct use of the imported value as a string will fail. E.g., `import font from './font.ttf'` and then `fontFamily: font` is wrong.","severity":"gotcha","affected_versions":">=5.0"},{"fix":"Run `set CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github` in your terminal before `npm install`.","message":"On Windows, building may fail if `CN_FONT_SPLIT_GH_HOST` is not set. Without it, the Rust binary download may timeout.","severity":"gotcha","affected_versions":">=5.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install -D vite-plugin-font` and ensure your project uses ES modules (type: 'module' in package.json or use .mjs).","cause":"Package not installed or ESM-only import used in CommonJS context.","error":"Error: Cannot find module 'vite-plugin-font'"},{"fix":"Use `Font.vite()` (or `Font.webpack()` for Webpack).","cause":"Calling `new Font()` or `Font()` directly instead of using the `.vite()` or `.webpack()` method.","error":"TypeError: Font is not a constructor"},{"fix":"Import as: `import { css } from './font.ttf'` (with named exports).","cause":"Trying to access `css.family` without destructuring the side-effect import.","error":"Cannot read properties of undefined (reading 'family')"},{"fix":"Set `CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github` before install.","cause":"Network issue fetching Rust binary from GitHub; common in China without environment variable.","error":"Failed to download font binary: getaddrinfo ENOTFOUND"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}