{"id":22928,"library":"vite-plugin-webfont-dl","title":"vite-plugin-webfont-dl","description":"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.","status":"active","version":"3.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/feat-agency/vite-plugin-webfont-dl","tags":["javascript","vite","vite-plugin","web-font","webfont","webfont-dl","webfont-download","google-fonts","bunny-fonts","typescript"],"install":[{"cmd":"npm install vite-plugin-webfont-dl","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-webfont-dl","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-webfont-dl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency – plugin requires Vite's plugin API (versions 2 through 8 supported)","package":"vite","optional":false},{"reason":"used for persistent caching of downloaded font files (v6+ since plugin v3.10.0)","package":"flat-cache","optional":false}],"imports":[{"note":"Plugin uses default export; named export does not exist. CommonJS require breaks ESM-only packages (default import required).","wrong":"const { webfontDownload } = require('vite-plugin-webfont-dl')","symbol":"webfontDownload","correct":"import webfontDownload from 'vite-plugin-webfont-dl'"},{"note":"Common mistake: using named import instead of default import. The plugin exports a single default function.","wrong":"import { webfontDownload } from 'vite-plugin-webfont-dl'","symbol":"webfontDownload","correct":"import webfontDownload from 'vite-plugin-webfont-dl'"},{"note":"TypeScript users should import the options type for type safety. Not available in CJS.","wrong":"","symbol":"type VitePluginWebfontDlOptions","correct":"import type { VitePluginWebfontDlOptions } from 'vite-plugin-webfont-dl'"}],"quickstart":{"code":"// vite.config.js\nimport webfontDownload from 'vite-plugin-webfont-dl';\n\nexport default {\n  plugins: [\n    webfontDownload([\n      'https://fonts.googleapis.com/css2?family=Roboto:wght@100;400&display=swap'\n    ], {\n      injectTo: 'head-prepend',\n      fontsSubfolder: 'fonts',\n      verbose: true\n    })\n  ]\n};","lang":"javascript","description":"Shows basic usage with config: pass font CSS URL(s) and optional settings like inject position and subfolder."},"warnings":[{"fix":"Delete node_modules/.cache/vite-plugin-webfont-dl or run vite with --force.","message":"v3.10.0 migrated from flat-cache v5 to v6, which may invalidate existing cache. Use '--force' to rebuild.","severity":"breaking","affected_versions":">=3.10.0"},{"fix":"Add font link tags in index.html or use simple config with explicit CSS URLs.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set throwErrors: true to get explicit errors during build.","message":"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.","severity":"deprecated","affected_versions":">=3.10.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install vite flat-cache --save-dev' or ensure your package manager installs peer dependencies.","cause":"Missing peer dependency 'vite' or 'flat-cache' not installed.","error":"Could not resolve dependency: ..."},{"fix":"Delete the cache folder and rebuild: rm -rf node_modules/.cache/vite-plugin-webfont-dl && npm run build.","cause":"Cache directory corruption or permission issue.","error":"Error: ENOENT: no such file or directory, open '.../node_modules/.cache/vite-plugin-webfont-dl/...'"},{"fix":"Install with 'npm i vite-plugin-webfont-dl -D' and ensure import is default: import webfontDownload from 'vite-plugin-webfont-dl'.","cause":"Package not installed or incorrect import path.","error":"Cannot find module 'vite-plugin-webfont-dl'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}