🔠 Webfont Download Vite Plugin ⚡
Automatically collects webfont links, imports, and definitions from your Vite project, downloads CSS and font files (privacy-first), adds the fonts to your bundle (or serves them through the dev server), and injects font definitions using a non-render-blocking method. External CSS and font files are stored in a persistent file cache, making them available for offline development.
📦 Install
npm i vite-plugin-webfont-dl -D
📖 Table of Contents
- 📦 Install
- Usage:
- 🚀 That's all!
- 🔌 Laravel
- 📸 Screenshot
- 🧩 Supported webfont providers
- 🛠️ Options
- ❓ Third-party webfonts
- 🔮 How it works
- 📊 Benchmark
- 📚 Resources
- 📄 License
😎 Usage: Zero config [method A]
Extracts, downloads, and injects fonts from the original Google Fonts code snippet.
- Select your font families from your webfont provider (e.g. Google Fonts) and copy the code from the "Use on the web" block into your
<head>
:<link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400&family=Roboto:wght@100&display=swap" rel="stylesheet">
Add
webfontDownload
to your Vite plugins without any configuration. The plugin will automatically handle everything:// vite.config.js import webfontDownload from 'vite-plugin-webfont-dl'; export default { plugins: [ webfontDownload(), ], };
- The original webfont tags will be replaced in
dist/index.html
:<style>@font-face{font-family:...;src:url(/assets/foo-xxxxxxxx.woff2) format('woff2'),url(/assets/bar-yyyyyyyy.woff) format('woff')}...</style>
🦄 Usage: Simple config [method B]
Extracts, downloads, and injects fonts from the configured webfont CSS URL(s).
- Select your font families from your webfont provider (e.g. Google Fonts) and copy the CSS URL(s) from the "Use on the web" code block:
<link href="[CSS URL]" rel="stylesheet">
Add
webfontDownload
to your Vite plugins with the selected Google Fonts CSS URL(s):// vite.config.js import webfontDownload from 'vite-plugin-webfont-dl'; export default { plugins: [ webfontDownload([ 'https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap', 'https://fonts.googleapis.com/css2?family=Fira+Code&display=swap' ]), ], };
🚀 That's all!
The webfonts are injected and ready to use.
The plugin works seamlessly whether you are running a local development server or building for production.
h1 {
font-family: 'Press Start 2P', cursive;
}
h2 {
font-family: 'Fira Code', monospace;
}
🔌 Laravel
To use with the Laravel Vite Plugin, add this line to your Blade file:
@vite('webfonts.css')
📸 Screenshot

🧩 Supported webfont providers
- Google Fonts: works with Zero config or Simple config
- Bunny Fonts: works with Zero config or Simple config
- Fontshare: works with Zero config or Simple config
- Fira Code, Hack fonts (
cdn.jsdelivr.net
): works with Zero config or Simple config - Inter font (
rsms.me
): works with Zero config or Simple config - Any provider with CSS containing
@font-face
definitions works with Simple config
🛠️ Options
injectAsStyleTag
(boolean
, default:true
):
Inject webfonts as a<style>
tag (embedded CSS) or as an external.css
file.minifyCss
(boolean
, default: value ofbuild.minify
):
Minify CSS code during the build process.embedFonts
(boolean
, default:false
):
Embed base64-encoded fonts into CSS.
In some cases, this can increase the file size if the CSS contains multiple references to the same font file. Exampleasync
(boolean
, default:true
):
Prevents the use of inline event handlers inwebfonts.css
that can cause Content Security Policy issues.
Only applicable wheninjectAsStyleTag:false
.cache
(boolean
, default:true
):
Persistently stores downloaded CSS and font files in a local file cache.
If set tofalse
, the existing cache will be deleted.proxy
(false|AxiosProxyConfig
, default:false
):
Proxy configuration for network requests.assetsSubfolder
(string
, default:''
):
Moves downloaded font files to a separate subfolder within the assets directory.throwError
(boolean
, default:false
):
If set totrue
, the plugin will throw an error and stop the build if any font download or processing fails. Iffalse
, errors are logged as warnings and the build continues.subsetsAllowed
(string[]
, default:[]
):
Restricts downloaded fonts to the specified Unicode subsets (e.g.,['latin', 'cyrillic']
). Only font files matching these subsets will be included. Leave empty to allow all subsets.
Usage example:
ViteWebfontDownload(
[],
{
injectAsStyleTag: true,
minifyCss: true,
embedFonts: false,
async: true,
cache: true,
proxy: false,
assetsSubfolder: '',
}
)
Or:
ViteWebfontDownload(
[
'https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap',
],
{
injectAsStyleTag: true,
minifyCss: true,
embedFonts: false,
async: true,
cache: true,
proxy: false,
assetsSubfolder: '',
}
)
❓ Third-party webfonts
⚠️ Using the standard method to add third-party webfonts (Google Fonts, Bunny Fonts or Fontshare) to a webpage can significantly slow down page load. Lighthouse and PageSpeed Insights call them "render-blocking resources", which means the page can't fully render until the webfonts CSS has been fetched from the remote server.
📈 By avoiding render-blocking resources caused by third-party webfonts, you can boost page performance, leading to a better user experience and improved SEO results.
⚙️ The plugin downloads the specified fonts from the third-party webfont service (like Google Fonts) and dynamically injects them (as an internal or external stylesheet) into your Vite project, transforming third-party webfonts into self-hosted ones. 🤩
🔐 In addition to the significant performance increase, your visitors will also benefit from privacy protection, since there is no third-party server involved.
🔮 How it works
📉 Google Fonts
Google Fonts generates the following code, which you have to inject into your website's <head>
, example:
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Fira+Code&display=swap" rel="stylesheet">
📱 What happens on the client-side with Google Fonts:
- The first line gives a hint to the browser to begin the connection handshake (DNS, TCP, TLS) with
fonts.googleapis.com
. This happens in the background to improve performance. [preconnect
] - The second line is another preconnect hint to
fonts.gstatic.com
. [preconnect
] - The third line instructs the browser to load and use a CSS stylesheet file from
fonts.googleapis.com
(withfont-display:swap
). [stylesheet
] - The browser downloads the CSS file and starts to parse it. The parsed CSS is a set of
@font-face
definitions containing font URLs from thefonts.gstatic.com
server. - The browser starts to download all relevant fonts from
fonts.gstatic.com
. - After the fonts are successfully downloaded, the browser swaps the fallback fonts for the downloaded ones.
🆚
📈 Webfont-DL Vite Plugin
In contrast, the Webfont-DL plugin does most of the work at build time, leaving minimal work for the browser.
Webfont-DL plugin
- Collects the webfont CSS URLs (from plugin config,
index.html
, and generated CSS) - Downloads the webfont CSS file(s)
- Extracts the font URLs
- Downloads the fonts
- Adds the fonts to the bundle
- Generates embedded CSS (
<style>
tag) or an external webfont CSS file - Adds them to the bundle and injects the following code into your website's
<head>
using a non-render-blocking method, example:
<style>
@font-face {
font-family: 'Fira Code';
font-style: normal;
font-weight: 300;
font-display: swap;
src: url(/assets/uU9eCBsR6Z2vfE9aq3bL0fxyUs4tcw4W_GNsJV37Nv7g.9c348768.woff2) format('woff2');
unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
}
...
</style>
Or (using the dev server or injectAsStyleTag: false
option):
<link rel="preload" as="style" href="/assets/webfonts.b904bd45.css">
<link rel="stylesheet" media="print" onload="this.onload=null;this.removeAttribute('media');" href="/assets/webfonts.b904bd45.css">
📱 What happens on the client-side with the Webfont-DL plugin:
- Loads fonts from the embedded CSS (
<style>
tag).
Or
- The first line instructs the browser to prefetch a CSS file for later use as a stylesheet. [
preload
] - The second line instructs the browser to load and use that CSS file as a
print
stylesheet (non-render-blocking). After loading, it is promoted to anall
media type stylesheet (by removing themedia
attribute). [stylesheet
]
📊 Benchmark
Starter Vite project with
▶️ Standard Google Fonts | 🆚 | ▶️ Webfont DL Vite plugin |
---|---|---|
🔗 webfont.feat.agency | | 🔗 webfont-dl.feat.agency |
📚 Resources
📄 License
MIT License © 2022 feat.