vite-plugin-webfont-dl

3.12.0 verified Mon Apr 27 auth: no javascript

Vite plugin (v3.12.0) that automatically downloads and injects webfonts (Google Fonts, Bunny Fonts, Fontshare, etc.) during build and dev. It extracts font links from HTML or config, downloads CSS and font files (privacy-first, no external CDN requests at runtime), adds them to the bundle, and injects a non-render-blocking @font-face style tag. Features persistent cache (offline development), support for subset queries, custom fontsSubfolder, and various injection options. Actively maintained (multiple releases per month), supports Vite 2-8 and Rolldown, ships TypeScript types. Differentiator: zero-config and full download/injection pipeline vs alternatives like vite-plugin-google-fonts that only inject a link tag.

Common errors

error Could not resolve dependency: ... ↓

cause Missing peer dependency 'vite' or 'flat-cache' not installed.

fix

Run 'npm install vite flat-cache --save-dev' or ensure your package manager installs peer dependencies.

error Error: ENOENT: no such file or directory, open '.../node_modules/.cache/vite-plugin-webfont-dl/...' ↓

cause Cache directory corruption or permission issue.

fix

Delete the cache folder and rebuild: rm -rf node_modules/.cache/vite-plugin-webfont-dl && npm run build.

error Cannot find module 'vite-plugin-webfont-dl' ↓

cause Package not installed or incorrect import path.

fix

Install with 'npm i vite-plugin-webfont-dl -D' and ensure import is default: import webfontDownload from 'vite-plugin-webfont-dl'.

Warnings

breaking v3.10.0 migrated from flat-cache v5 to v6, which may invalidate existing cache. Use '--force' to rebuild. ↓

fix Delete node_modules/.cache/vite-plugin-webfont-dl or run vite with --force.

gotcha Zero-config mode scans <link> tags in index.html for Google Fonts; if none found, nothing is downloaded. Ensure the tags are present before the plugin runs. ↓

fix Add font link tags in index.html or use simple config with explicit CSS URLs.

deprecated Option 'throwErrors' was added in v3.10.0 to replace silent error catching; the previous behavior (silent) is still default but may change in future major. ↓

fix Set throwErrors: true to get explicit errors during build.

Install

npm install vite-plugin-webfont-dl

yarn add vite-plugin-webfont-dl

pnpm add vite-plugin-webfont-dl

Imports

webfontDownload
wrong
```
const { webfontDownload } = require('vite-plugin-webfont-dl')
```
correct
```
import webfontDownload from 'vite-plugin-webfont-dl'
```
Plugin uses default export; named export does not exist. CommonJS require breaks ESM-only packages (default import required).
webfontDownload
wrong
```
import { webfontDownload } from 'vite-plugin-webfont-dl'
```
correct
```
import webfontDownload from 'vite-plugin-webfont-dl'
```
Common mistake: using named import instead of default import. The plugin exports a single default function.
type VitePluginWebfontDlOptions
```
import type { VitePluginWebfontDlOptions } from 'vite-plugin-webfont-dl'
```
TypeScript users should import the options type for type safety. Not available in CJS.

Quickstart

Shows basic usage with config: pass font CSS URL(s) and optional settings like inject position and subfolder.

// vite.config.js
import webfontDownload from 'vite-plugin-webfont-dl';

export default {
  plugins: [
    webfontDownload([
      'https://fonts.googleapis.com/css2?family=Roboto:wght@100;400&display=swap'
    ], {
      injectTo: 'head-prepend',
      fontsSubfolder: 'fonts',
      verbose: true
    })
  ]
};