unplugin-fonts

㊗️ Universal Webfont loader - Unfonts

English | 中文

📢 Fork Information This repository is forked from unplugin-fonts by cssninjaStudio. Enhanced with additional Webpack integration features, framework compatibility improvements, and comprehensive Chinese documentation.

Original Repository: https://github.com/cssninjaStudio/unplugin-fonts Fork Maintainer: cklwblove

This plugin goes beyond just generating font-face rules - it also takes care of link preload and prefetch, optimizing font loading for a faster and more efficient user experience.

Unfonts currently supports popular font providers like Typekit, Google Fonts, and Fontsource, as well as custom fonts. This gives you the flexibility to choose from a vast range of fonts and seamlessly integrate them into your projects.

With Unfonts, you no longer have to manually manage font files and font-face rules, or worry about slow loading times. Our package does all the heavy lifting for you, so you can focus on creating amazing content with ease.

View configuration:

• Typekit
• Google Fonts
• Custom Fonts
• Fontsource

Install

npm i --save-dev @winner-fed/unplugin-fonts # pnpm add -D @winner-fed/unplugin-fonts

// vite.config.ts
import Unfonts from '@winner-fed/unplugin-fonts/vite'

export default defineConfig({
  plugins: [
    Unfonts({ /* options */ }),
  ],
})

Example: examples/vite

// webpack.config.js
const UnfontsWebpack = require('@winner-fed/unplugin-fonts/webpack').default

module.exports = {
  /* ... */
  plugins: [
    UnfontsWebpack({
      google: {
        families: ['Inter:400,500,600,700', 'Material Icons']
      },
      custom: {
        families: [{
          name: 'MyFont',
          src: './assets/fonts/*.woff2',
          transform(font) {
            // 可选：根据文件名自动设置字体权重
            if (font.basename.includes('Bold')) {
              font.weight = 700
            }
            else if (font.basename.includes('Medium')) {
              font.weight = 500
            }
            return font
          }
        }],
        display: 'swap',
        preload: true,
        injectTo: 'head-prepend'
      }
    })
  ]
}

Note Webpack integration supports multiple scenarios:

1. Auto mode (with html-webpack-plugin): Automatically injects font tags into HTML
2. Manual mode (without html-webpack-plugin): Provides utilities for manual font injection
3. Framework mode (WinJS, etc.): Uses virtual modules for CSS injection and manual font tag injection

With html-webpack-plugin (Recommended)

Auto injection works seamlessly:

// webpack.config.js
const UnfontsWebpack = require('@winner-fed/unplugin-fonts/webpack').default
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {
  plugins: [
    new HtmlWebpackPlugin({ template: './src/index.html' }),
    UnfontsWebpack({
      google: { families: ['Inter:400,600'] }
    })
  ]
}

Without html-webpack-plugin (Manual Mode)

When no html-webpack-plugin is detected, you'll need to handle font loading manually:

import { autoInject, injectToHead } from '@winner-fed/unplugin-fonts/head'
// In your application entry point
import 'unfonts.css' // Import CSS for custom fonts (if any)

// Option 1: Manual injection
injectToHead() // Call when your app initializes

// Option 2: Auto injection
autoInject() // Automatically handles DOM ready state

Framework Integration (WinJS, etc.)

For frameworks with custom build processes:

import { injectToHead } from '@winner-fed/unplugin-fonts/head'
// In your application entry point
import 'unfonts.css' // Auto-inject custom font CSS via virtual module

// Manual injection for Google Fonts/Typekit (when HTML injection is not possible)
injectToHead()

Examples:

• With html-webpack-plugin: examples/webpack
• Without html-webpack-plugin: examples/webpack-no-html
• WinJS Framework: examples/winjs-demo - 演示虚拟模块CSS注入和字体权重自动识别

// nuxt.config.js
export default {
  modules: [
    ['@winner-fed/unplugin-fonts/nuxt'],
  ],
  unfonts: {
    /* options */
  }
}

Example: examples/nuxt

import { sveltekit } from '@sveltejs/kit/vite'
import Unfonts from '@winner-fed/unplugin-fonts/vite'
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    sveltekit(),
    Unfonts({
      /* options */
    })
  ]
})

<script>
// +layout.svelte
import { links } from '@winner-fed/unplugin-fonts/head'
</script>

<svelte:head>
  {#each links as link}
    <link {...link?.attrs || {}} />
  {/each}
</svelte:head>

Example: examples/sveltekit

import Unfonts from '@winner-fed/unplugin-fonts/astro'
// astro.config.js
import { defineConfig } from 'astro/config'

export default defineConfig({
  integrations: [
    Unfonts({
      /* options */
    })
  ]
})

---
// src/pages/index.astro
import Unfont from '@winner-fed/unplugin-fonts/astro/component.astro';
---

<html>
  <head>
    <Unfont />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Example: examples/astro

// vite.config.ts
-import { VitePluginFonts } from 'vite-plugin-fonts'
+import Unfonts from '@winner-fed/unplugin-fonts/vite'

export default defineConfig({
  plugins: [
-    VitePluginFonts({
+    Unfonts({
      /* options */
    }),
  ],
})

// main.ts
-import 'virtual:fonts.css'
+import 'unfonts.css'

Import generated @font-rules CSS

Note Required if using custom or fontsource providers

import 'unfonts.css'

This virtual module automatically generates and injects CSS for:

• Custom font @font-face rules
• Fontsource font imports

The module works across all supported bundlers (Vite, Webpack, etc.) and handles font file processing automatically.

Providers

Typekit

Load fonts from Typekit.

Unfonts({
  // Typekit API
  typekit: {
    /**
     * Typekit project id
     */
    id: '<projectId>',

    /**
     * customizes the base URL for the font request
     * default: 'https://use.typekit.net/'
     */
    fontBaseUrl: 'https://use.typekit.net/',

    /**
     * enable non-blocking renderer
     *   <link rel="preload" href="xxx" as="style" onload="this.rel='stylesheet'">
     * default: true
     */
    defer: true,

    /**
     * define where the font load tags should be inserted
     * default: 'head-prepend'
     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'
     */
    injectTo: 'head-prepend',
  },
})

Google Fonts

Load fonts from Google Fonts.

Unfonts({
  // Google Fonts API V2
  google: {
    /**
     * enable preconnect link injection
     *   <link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin>
     * default: true
     */
    preconnect: false,

    /**
     * allow preconnect to be customized
     * default: 'https://fonts.gstatic.com'
     */
    preconnectUrl: 'https://fonts.gstatic.com',

    /**
     * customizes the base URL for the font request
     * default: 'https://fonts.googleapis.com/css2'
     */
    fontBaseUrl: 'https://fonts.googleapis.com/css2',

    /**
     * values: auto, block, swap(default), fallback, optional
     * default: 'swap'
     */
    display: 'block',

    /**
     * define which characters to load
     * default: undefined (load all characters)
     */
    text: 'ViteAwsom',

    /**
     * define where the font load tags should be inserted
     * default: 'head-prepend'
     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'
     */
    injectTo: 'head-prepend',

    /**
     * Fonts families lists
     */
    families: [
      // families can be either strings (only regular 400 will be loaded)
      'Source Sans Pro',

      // or objects
      {
        /**
         * Family name (required)
         */
        name: 'Roboto',

        /**
         * Family styles
         */
        styles: 'ital,wght@0,400;1,200',

        /**
         * enable non-blocking renderer
         *   <link rel="preload" href="xxx" as="style" onload="this.rel='stylesheet'">
         * default: true
         */
        defer: true,
      },
    ],
  },
})

Custom Fonts

Load custom fonts from files.

Unfonts({
  // Custom fonts.
  custom: {
    /**
     * Fonts families lists
     */
    families: [{
      /**
       * Name of the font family.
       */
      name: 'Roboto',
      /**
       * Local name of the font. Used to add `src: local()` to `@font-rule`.
       */
      local: 'Roboto',
      /**
       * Regex(es) of font files to import. The names of the files will
       * predicate the `font-style` and `font-weight` values of the `@font-rule`'s.
       */
      src: './src/assets/fonts/*.ttf',

      /**
       * This function allow you to transform the font object before it is used
       * to generate the `@font-rule` and head tags.
       */
      transform(font) {
        // Auto-detect font weight from filename
        if (font.basename.includes('Bold')) {
          font.weight = 700
        }
        else if (font.basename.includes('SemiBold')) {
          font.weight = 600
        }
        else if (font.basename.includes('Medium')) {
          font.weight = 500
        }
        else if (font.basename.includes('Light')) {
          font.weight = 300
        }

        // we can also return null to skip the font
        return font
      }
    }],

    /**
     * Defines the default `font-display` value used for the generated
     * `@font-rule` classes.
     */
    display: 'auto',

    /**
     * Using `<link rel="preload">` will trigger a request for the WebFont
     * early in the critical rendering path, without having to wait for the
     * CSSOM to be created.
     */
    preload: true,

    /**
     * Using `<link rel="prefetch">` is intended for prefetching resources
     * that will be used in the next navigation/page load
     * (e.g. when you go to the next page)
     *
     * Note: this can not be used with `preload`
     */
    prefetch: false,

    /**
     * define where the font load tags should be inserted
     * default: 'head-prepend'
     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'
     */
    injectTo: 'head-prepend',
  },

})

Fontsource

Load fonts from Fontsource packages.

Note You will need to install @fontsource/<font> packages.

Unfonts({
  // Fontsource API
  fontsource: {
    /**
     * Fonts families lists
     */
    families: [
      // families can be either strings (load default font set)
      // Require the `@fontsource/abeezee` package to be installed.
      'ABeeZee',
      'Inter Variable', // Require the `@fontsource-variable/inter` package to be installed.
      {
        /**
         * Name of the font family.
         * Require the `@fontsource/roboto` package to be installed.
         */
        name: 'Roboto',
        /**
         * Load only a subset of the font family.
         */
        weights: [400, 700],
        /**
         * Restrict the font styles to load.
         */
        styles: ['italic', 'normal'],
        /**
         * Use another font subset.
         */
        subset: 'latin-ext',
      },
      {
        /**
         * Name of the font family.
         * Require the `@fontsource-variable/cabin` package to be installed.
         */
        name: 'Cabin',
        /**
         * When using variable fonts, you can choose which axes to load.
         */
        variable: {
          wght: true,
          slnt: true,
          ital: true,
        },
      },
    ],
  },
})

Typescript Definitions

{
  "compilerOptions": {
    "types": ["@winner-fed/unplugin-fonts/client"]
  }
}

or

// declaration.d.ts
/// <reference types="@winner-fed/unplugin-fonts/client" />

Resources

• https://web.dev/optimize-webfont-loading/
• https://csswizardry.com/2020/05/the-fastest-google-fonts/
• (unmaintained) https://www.npmjs.com/package/webfontloader

Credits & Acknowledgments

This project is a fork of the original unplugin-fonts created by cssninjaStudio.

Original Authors

• cssninjaStudio - Original plugin development

Fork Contributors

• cklwblove - Webpack enhancements, framework integration, Chinese documentation

Enhancements in This Fork

• ✨ Enhanced Webpack integration with multiple modes support
• 🔧 Improved framework compatibility (WinJS, etc.)
• 🎯 Virtual module system for better CSS injection
• 📖 Comprehensive Chinese documentation
• 🚀 Advanced font weight auto-detection
• 🛠 Better error handling and debugging tools

License

This project maintains the same MIT license as the original repository.

Original Project: https://github.com/cssninjaStudio/unplugin-fonts