Registry / web-framework / vite-plugin-webfont-dl

vite-plugin-webfont-dl

library3.12.0jsnpmunverified

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.

web-framework

npm install vite-plugin-webfont-dl

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-WEBFON

vite-plugin-webfont-dl

web-frameworkjavascriptv3.12.0

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.

webfontDownload

✓ import webfontDownload from 'vite-plugin-webfont-dl'

✗ const { webfontDownload } = require('vite-plugin-webfont-dl')

Plugin uses default export; named export does not exist. CommonJS require breaks ESM-only packages (default import required).

webfontDownload

✓ import webfontDownload from 'vite-plugin-webfont-dl'

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

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 }) ] };

Debug

Known issues

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

affects: >=3.10.0

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

affects: >=1.0.0

deprecatedOption '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.

affects: >=3.10.0

Errors

Common errors & fixes

Could not resolve dependency: ...

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: ENOENT: no such file or directory, open '.../node_modules/.cache/vite-plugin-webfont-dl/...'

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.

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

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

Upgrade

Version history

3.12.0latest on npm

Audit

Dependencies

viterequiredpeer dependency – plugin requires Vite's plugin API (versions 2 through 8 supported)

flat-cacherequiredused for persistent caching of downloaded font files (v6+ since plugin v3.10.0)

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/feat-agency/vite-plugin-webfont-dl ↗

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

homepagehttps://webfont-dl.feat.agency ↗