Registry / web-framework / vite-plugin-font

vite-plugin-font

library5.1.2jsnpmunverified

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.

web-framework devops

npm install vite-plugin-font

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-FONT

vite-plugin-font

web-frameworkjavascriptv5.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import Font from 'vite-plugin-font'

✗ const Font = require('vite-plugin-font')

Plugin is ESM-only; CommonJS require will fail.

viteFont

✓ import viteFont from 'vite-plugin-font'

✗ import { vite } from 'vite-plugin-font'

Default export is a function; access .vite() method.

Font.vite()

✓ Font.vite()

✗ Font()

Since v5, you must call .vite() for Vite config, not the default function directly.

css / fontFamilyFallback

✓ import { css, fontFamilyFallback } from './font.ttf';

✗ import font from './font.ttf'

Font files are treated as modules exporting css (with family, url, etc.) and fontFamilyFallback string. Do not import as raw asset.

Basic setup for Vite: install plugin, add to config, then import font file as module to get CSS properties and fallback.

// vite.config.js import { defineConfig } from 'vite'; import Font from 'vite-plugin-font'; export default defineConfig({ plugins: [Font.vite()], }); // Then in your component: import { css, fontFamilyFallback } from './public/SmileySans-Oblique.ttf'; document.body.style.fontFamily = `"${css.family}", ${fontFamilyFallback}`;

Debug

Known issues

breakingSince 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`.

fix

Use `Font.vite()` (or `Font.webpack()` for Webpack).

affects: >=5.0

breakingRemoved support for Node.js <18 in v7.

fix

Upgrade to Node.js 18 or later.

affects: >=7.0

deprecatedThe `family` export from font imports is deprecated in favor of `css.family`.

fix

Use `import { css } from '...'` and access `css.family`.

affects: >=5.1

gotchaFont 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.

fix

Destructure: `import { css, fontFamilyFallback } from './font.ttf'`.

affects: >=5.0

gotchaOn Windows, building may fail if `CN_FONT_SPLIT_GH_HOST` is not set. Without it, the Rust binary download may timeout.

fix

Run `set CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github` in your terminal before `npm install`.

affects: >=5.0

Errors

Common errors & fixes

Error: Cannot find module 'vite-plugin-font'

Package not installed or ESM-only import used in CommonJS context.

fix

Run `npm install -D vite-plugin-font` and ensure your project uses ES modules (type: 'module' in package.json or use .mjs).

TypeError: Font is not a constructor

Calling `new Font()` or `Font()` directly instead of using the `.vite()` or `.webpack()` method.

fix

Use `Font.vite()` (or `Font.webpack()` for Webpack).

Cannot read properties of undefined (reading 'family')

Trying to access `css.family` without destructuring the side-effect import.

fix

Import as: `import { css } from './font.ttf'` (with named exports).

Failed to download font binary: getaddrinfo ENOTFOUND

Network issue fetching Rust binary from GitHub; common in China without environment variable.

fix

Set `CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github` before install.

Upgrade

Version history

5.1.2latest on npm

Audit

Dependencies

cn-font-splitrequiredCore font-splitting engine; Rust-native performance

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/KonghaYao/cn-font-split.git#release ↗

packagehttps://www.npmjs.com/package/vite-plugin-font ↗

homepagehttps://www.cnfont.com ↗