vite-plugin-font

5.1.2 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause 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).

error TypeError: Font is not a constructor ↓

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

fix

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

error Cannot read properties of undefined (reading 'family') ↓

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

fix

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

error Failed to download font binary: getaddrinfo ENOTFOUND ↓

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

Warnings

breaking 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`. ↓

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

breaking Removed support for Node.js <18 in v7. ↓

fix Upgrade to Node.js 18 or later.

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

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

gotcha 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. ↓

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

gotcha On 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`.

Install

npm install vite-plugin-font

yarn add vite-plugin-font

pnpm add vite-plugin-font

Imports

default

wrong

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

correct

import Font from 'vite-plugin-font'

Plugin is ESM-only; CommonJS require will fail.

viteFont

wrong

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

correct

import viteFont from 'vite-plugin-font'

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

Font.vite()
wrong
```
Font()
```
correct
```
Font.vite()
```
Since v5, you must call .vite() for Vite config, not the default function directly.
css / fontFamilyFallback
wrong
```
import font from './font.ttf'
```
correct
```
import { css, fontFamilyFallback } from './font.ttf';
```
Font files are treated as modules exporting css (with family, url, etc.) and fontFamilyFallback string. Do not import as raw asset.

Quickstart

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}`;