vite-plugin-font
v5.1.0
Published
An automatic Web Font optimization plugin that supports many platforms such as Vite, Next, Nuxt, and more.
Downloads
52,519
Maintainers
Readme
🔠 vite-plugin-font 5.0 ⚡
Developed and supported by the Chinese WebFont Project, vite-plugin-font is a powerful and simple Vite font build tool that can split large fonts into Webfonts. It is powered by cn-font-split for Rust-native level build speed.
We provide an Extremely lightweight optimization solution for first-screen optimization and a full-scale optimization for large text sites, achieving extreme optimization of Chinese fonts in the front-end toolchain.
⚡ Features
- ⚡ 50% faster speed, no fear of lag
- ⚙️ Automatic CJK (Chinese, Japanese, Korean) font splitting, extremely fast on-demand loading
- 🚀 Automatically optimizes the first screen based on characters used in your project
- 🔄 Automatically converts fonts to woff2 format, no need to worry about size issues
- 🌐 Automatically adds local adaptation, reduces cumulative content shifts, SSR support
- 📤 Exports font information, supports tree shaking optimization
- 🎨 Pure CSS, no runtime data, multi-platform compatibility
- 📦 Automatically reduces Chinese CLS offset
| Type | Vite, Astro, Qwik | Nuxt | Next | Webpack, Rspack | | ----------------------------- | -------------------------- | ------------- | ------------- | --------------------------- | | Full-scale optimization | ✅ | ✅ | ✅ | ✅ | | Extremely lightweight optimization | ✅ | ✅ | ✅ | ✅ |
- Full-scale optimization is suitable for blogs, documentation websites, which require a large amount of uncertain text. It can achieve full-scale font rendering and has excellent cache performance when combined with CDN.
- Extremely lightweight optimization is suitable for official websites, promotional web pages, etc., where quick rendering is required. It collects the characters used in your code and only loads these characters, providing excellent rendering performance. The required font size is approximately 10% of full-scale optimization.
📦 Install
# 国内请设置环境变量, windows 用 set
export CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github
# set CN_FONT_SPLIT_GH_HOST=https://ik.imagekit.io/github # windows
npm i -D vite-plugin-font
import { css, fontFamilyFallback } from '../demo/public/SmileySans-Oblique.ttf';
document.body.style.fontFamily = `"${css.family}", ` + fontFamilyFallback;
✨ Config
Vite
Almost all frameworks that use Vite as the underlying compilation framework can use
vite-plugin-font
by definingplugins
.
// vite.config.js
import { defineConfig } from 'vite';
import Font from 'vite-plugin-font';
export default defineConfig({
plugins: [Font.vite()],
});
Nuxt
// https://nuxt.com/docs/api/configuration/nuxt-config
import font from 'vite-plugin-font';
export default defineNuxtConfig({
devtools: { enabled: false },
vite: {
plugins: [font.vite({})],
},
compatibilityDate: '2024-10-26',
});
Next
// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
webpack: (config, options) => {
config.plugins.push(viteFont.webpack());
return config;
},
};
export default nextConfig;
Webpack
// webpack.config.js or rspack.config.js
const path = require('path');
module.exports = {
plugins: [viteFont.webpack()],
};
🚀 Usage
// Automatically injects CSS to import fonts and supports tree shaking optimization of font information!
import { css } from '../../demo/public/SmileySans-Oblique.ttf'; // Directly import font file
console.log(css.family, css.weight); // You can get CSS-related data here
export const App = () => {
return (
<div
style={{
fontFamily: css.family,
}}
></div>
);
};
Extremely Lightweight Optimization
Extremely lightweight optimization is suitable for official websites, promotional web pages, etc., where quick rendering is required. It collects the characters used in your code and only loads these characters, providing excellent rendering performance.
Add
scanFiles
, the way to add it for Nuxt and Webpack is slightly different, but both are adding scan files to the options.
// vite.config.js
import { defineConfig } from 'vite';
import Font from 'vite-plugin-font';
export default defineConfig({
plugins: [
Font.vite({
scanFiles: ['src/**/*.{vue,ts,tsx,js,jsx}'],
}),
],
});
Add
?subsets
to your link
// Automatically injects CSS to import fonts and supports tree shaking optimization of font information!
- import { css } from '../../demo/public/SmileySans-Oblique.ttf';
+ import { css } from '../../demo/public/SmileySans-Oblique.ttf?subsets';
console.log(css.family, css.weight); // You can get CSS-related data here
export const App = () => {
return (
<div
style={{
fontFamily: css.family,
}}
></div>
);
};
Separate Partition Optimization
Sometimes, we need to package fonts according to different page dimensions, so we can use a key to identify the range of scanFiles.
// This will match subset-1
import { css } from '../../demo/public/SmileySans-Oblique.ttf?subsets&key=subset-1';
import { defineConfig } from 'vite';
import Font from 'vite-plugin-font';
export default defineConfig({
plugins: [
Font.vite({
scanFiles: {
// ?subsets will match default
default: ['src/**/*.{json,js,jsx,ts,tsx,vue}'],
'subset-1': ['example/**/*.{json,js,jsx,ts,tsx,vue}'],
},
}),
],
});
TypeScript Support
The source code includes the src/font.d.ts
file, you can add it to tsconfig.json.
{
"compilerOptions": {
"types": ["vite-plugin-font/src/font"]
}
}
Input Parameters
For input parameters, please refer to the usage instructions of cn-font-split. Most parameters are universal.