{"id":15629764,"url":"https://github.com/cssninjastudio/unplugin-fonts","last_synced_at":"2025-05-14T15:06:21.075Z","repository":{"id":39494170,"uuid":"327101647","full_name":"cssninjaStudio/unplugin-fonts","owner":"cssninjaStudio","description":"Universal Webfont loader - Unfonts - based on https://web.dev/optimize-webfont-loading/","archived":false,"fork":false,"pushed_at":"2024-12-01T16:27:23.000Z","size":723,"stargazers_count":374,"open_issues_count":24,"forks_count":30,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T14:01:38.506Z","etag":null,"topics":["font-loading","google-fonts","typekit","vite","vite-plugin","webfontloader","webfonts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cssninjaStudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-05T19:42:40.000Z","updated_at":"2025-04-06T08:31:39.000Z","dependencies_parsed_at":"2023-11-19T00:28:10.371Z","dependency_job_id":"5d15e0ba-97ae-41b7-8998-baa19a7ea491","html_url":"https://github.com/cssninjaStudio/unplugin-fonts","commit_stats":{"total_commits":97,"total_committers":14,"mean_commits":6.928571428571429,"dds":0.2680412371134021,"last_synced_commit":"8bc315cf331c56c51ab2f6203c2608f951e1368a"},"previous_names":["stafyniaksacha/vite-plugin-fonts"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssninjaStudio%2Funplugin-fonts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssninjaStudio%2Funplugin-fonts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssninjaStudio%2Funplugin-fonts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssninjaStudio%2Funplugin-fonts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cssninjaStudio","download_url":"https://codeload.github.com/cssninjaStudio/unplugin-fonts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248748115,"owners_count":21155573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["font-loading","google-fonts","typekit","vite","vite-plugin","webfontloader","webfonts"],"created_at":"2024-10-03T10:28:37.695Z","updated_at":"2025-04-13T16:44:15.757Z","avatar_url":"https://github.com/cssninjaStudio.png","language":"TypeScript","readme":"# unplugin-fonts\n\n㊗️ Universal Webfont loader - Unfonts\n\n[![npm](https://img.shields.io/npm/v/unplugin-fonts.svg)](https://www.npmjs.com/package/unplugin-fonts)\n\nThis 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.\n\nUnfonts 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.\n\nWith 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.\n\nView configuration:\n- [Typekit](#typekit)\n- [Google Fonts](#google-fonts)\n- [Custom Fonts](#custom-fonts)\n- [Fontsource](#fontsource)\n\n## Install\n\n```bash\nnpm i --save-dev unplugin-fonts # pnpm add -D unplugin-fonts\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eVite\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// vite.config.ts\nimport Unfonts from 'unplugin-fonts/vite'\n\nexport default defineConfig({\n  plugins: [\n    Unfonts({ /* options */ }),\n  ],\n})\n```\n\nExample: [`examples/vite`](./examples/vite)\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003c!-- \u003cdetails\u003e\n\u003csummary\u003eRollup\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// rollup.config.js\nimport Starter from 'unplugin-fonts/rollup'\n\nexport default {\n  plugins: [\n    Starter({ /* options */ }),\n  ],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e --\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWebpack\u003c/summary\u003e\u003cbr\u003e\n\n\u003e **Warning**\n\u003e Not implemented yet\n\n```ts\n// webpack.config.js\nmodule.exports = {\n  /* ... */\n  plugins: [\n    require('unplugin-fonts/webpack')({ /* options */ })\n  ]\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNuxt\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// nuxt.config.js\nexport default {\n  modules: [\n    ['unplugin-fonts/nuxt'],\n  ],\n  unfonts: {\n    /* options */\n  }\n}\n```\n\nExample: [`examples/nuxt`](./examples/nuxt)\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003c!-- \u003cdetails\u003e\n\u003csummary\u003eVue CLI\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// vue.config.js\nmodule.exports = {\n  configureWebpack: {\n    plugins: [\n      require('unplugin-fonts/webpack')({ /* options */ }),\n    ],\n  },\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e --\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSvelteKit\u003c/summary\u003e\u003cbr\u003e\n\n```ts\nimport { sveltekit } from '@sveltejs/kit/vite'\nimport Unfonts from 'unplugin-fonts/vite'\n// vite.config.ts\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    sveltekit(),\n    Unfonts({\n      /* options */\n    })\n  ]\n})\n```\n\n```html\n\u003cscript\u003e\n// +layout.svelte\nimport { links } from 'unplugin-fonts/head'\n\u003c/script\u003e\n\n\u003csvelte:head\u003e\n  {#each links as link}\n    \u003clink {...link?.attrs || {}} /\u003e\n  {/each}\n\u003c/svelte:head\u003e\n```\n\nExample: [`examples/sveltekit`](./examples/sveltekit)\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAstro\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// astro.config.js\nimport { defineConfig } from 'astro/config'\nimport Unfonts from 'unplugin-fonts/astro'\n\nexport default defineConfig({\n  integrations: [\n    Unfonts({\n      /* options */\n    })\n  ]\n})\n```\n\n```astro\n---\n// src/pages/index.astro\nimport Unfont from 'unplugin-fonts/astro/component.astro';\n---\n\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003cUnfont /\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nExample: [`examples/astro`](./examples/astro)\n\n\u003cbr\u003e\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003eMigrating from \u003ccode\u003evite-plugin-fonts\u003c/code\u003e\u003c/summary\u003e\u003cbr\u003e\n\n```diff\n// vite.config.ts\n-import { VitePluginFonts } from 'vite-plugin-fonts'\n+import Unfonts from 'unplugin-fonts/vite'\n\nexport default defineConfig({\n  plugins: [\n-    VitePluginFonts({\n+    Unfonts({\n      /* options */\n    }),\n  ],\n})\n```\n\n```diff\n// main.ts\n-import 'virtual:fonts.css'\n+import 'unfonts.css'\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n## Import generated `@font-rules` CSS\n\n\u003e **Note**\n\u003e Required if using **custom** or **fontsource** providers\n\n```ts\nimport 'unfonts.css'\n```\n\n## Providers\n\n### Typekit\n\nLoad fonts from [Typekit](https://typekit.com/).\n\n```ts\nUnfonts({\n  // Typekit API\n  typekit: {\n    /**\n     * Typekit project id\n     */\n    id: '\u003cprojectId\u003e',\n\n    /**\n     * customizes the base URL for the font request\n     * default: 'https://use.typekit.net/'\n     */\n    fontBaseUrl: 'https://use.typekit.net/',\n\n    /**\n     * enable non-blocking renderer\n     *   \u003clink rel=\"preload\" href=\"xxx\" as=\"style\" onload=\"this.rel='stylesheet'\"\u003e\n     * default: true\n     */\n    defer: true,\n\n    /**\n     * define where the font load tags should be inserted\n     * default: 'head-prepend'\n     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'\n     */\n    injectTo: 'head-prepend',\n  },\n})\n```\n\n### Google Fonts\n\nLoad fonts from [Google Fonts](https://fonts.google.com/).\n\n```ts\nUnfonts({\n  // Google Fonts API V2\n  google: {\n    /**\n     * enable preconnect link injection\n     *   \u003clink rel=\"preconnect\" href=\"https://fonts.gstatic.com/\" crossorigin\u003e\n     * default: true\n     */\n    preconnect: false,\n\n    /**\n     * allow preconnect to be customized\n     * default: 'https://fonts.gstatic.com'\n     */\n    preconnectUrl: 'https://fonts.gstatic.com',\n\n    /**\n     * customizes the base URL for the font request\n     * default: 'https://fonts.googleapis.com/css2'\n     */\n    fontBaseUrl: 'https://fonts.googleapis.com/css2',\n\n    /**\n     * values: auto, block, swap(default), fallback, optional\n     * default: 'swap'\n     */\n    display: 'block',\n\n    /**\n     * define which characters to load\n     * default: undefined (load all characters)\n     */\n    text: 'ViteAwsom',\n\n    /**\n     * define where the font load tags should be inserted\n     * default: 'head-prepend'\n     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'\n     */\n    injectTo: 'head-prepend',\n\n    /**\n     * Fonts families lists\n     */\n    families: [\n      // families can be either strings (only regular 400 will be loaded)\n      'Source Sans Pro',\n\n      // or objects\n      {\n        /**\n         * Family name (required)\n         */\n        name: 'Roboto',\n\n        /**\n         * Family styles\n         */\n        styles: 'ital,wght@0,400;1,200',\n\n        /**\n         * enable non-blocking renderer\n         *   \u003clink rel=\"preload\" href=\"xxx\" as=\"style\" onload=\"this.rel='stylesheet'\"\u003e\n         * default: true\n         */\n        defer: true,\n      },\n    ],\n  },\n})\n```\n\n### Custom Fonts\n\nLoad custom fonts from files.\n\n```ts\nUnfonts({\n  // Custom fonts.\n  custom: {\n    /**\n     * Fonts families lists\n     */\n    families: [{\n      /**\n       * Name of the font family.\n       */\n      name: 'Roboto',\n      /**\n       * Local name of the font. Used to add `src: local()` to `@font-rule`.\n       */\n      local: 'Roboto',\n      /**\n       * Regex(es) of font files to import. The names of the files will\n       * predicate the `font-style` and `font-weight` values of the `@font-rule`'s.\n       */\n      src: './src/assets/fonts/*.ttf',\n\n      /**\n       * This function allow you to transform the font object before it is used\n       * to generate the `@font-rule` and head tags.\n       */\n      transform(font) {\n        if (font.basename === 'Roboto-Bold') {\n          // update the font weight\n          font.weight = 700\n        }\n\n        // we can also return null to skip the font\n        return font\n      }\n    }],\n\n    /**\n     * Defines the default `font-display` value used for the generated\n     * `@font-rule` classes.\n     */\n    display: 'auto',\n\n    /**\n     * Using `\u003clink rel=\"preload\"\u003e` will trigger a request for the WebFont\n     * early in the critical rendering path, without having to wait for the\n     * CSSOM to be created.\n     */\n    preload: true,\n\n    /**\n     * Using `\u003clink rel=\"prefetch\"\u003e` is intended for prefetching resources\n     * that will be used in the next navigation/page load\n     * (e.g. when you go to the next page)\n     *\n     * Note: this can not be used with `preload`\n     */\n    prefetch: false,\n\n    /**\n     * define where the font load tags should be inserted\n     * default: 'head-prepend'\n     *   values: 'head' | 'body' | 'head-prepend' | 'body-prepend'\n     */\n    injectTo: 'head-prepend',\n  },\n\n})\n```\n\n### Fontsource\n\nLoad fonts from [Fontsource](https://fontsource.org/) packages.\n\n\u003e **Note**\n\u003e You will need to install `@fontsource/\u003cfont\u003e` packages.\n\n```ts\nUnfonts({\n  // Fontsource API\n  fontsource: {\n    /**\n     * Fonts families lists\n     */\n    families: [\n      // families can be either strings (load default font set)\n      // Require the `@fontsource/abeezee` package to be installed.\n      'ABeeZee',\n      'Inter Variable', // Require the `@fontsource-variable/inter` package to be installed.\n      {\n        /**\n         * Name of the font family.\n         * Require the `@fontsource/roboto` package to be installed.\n         */\n        name: 'Roboto',\n        /**\n         * Load only a subset of the font family.\n         */\n        weights: [400, 700],\n        /**\n         * Restrict the font styles to load.\n         */\n        styles: ['italic', 'normal'],\n        /**\n         * Use another font subset.\n         */\n        subset: 'latin-ext',\n      },\n      {\n        /**\n         * Name of the font family.\n         * Require the `@fontsource-variable/cabin` package to be installed.\n         */\n        name: 'Cabin',\n        /**\n         * When using variable fonts, you can choose which axes to load.\n         */\n        variable: {\n          wght: true,\n          slnt: true,\n          ital: true,\n        },\n      },\n    ],\n  },\n})\n```\n\n## Typescript Definitions\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"unplugin-fonts/client\"]\n  }\n}\n```\n\nor\n\n```ts\n// declaration.d.ts\n/// \u003creference types=\"unplugin-fonts/client\" /\u003e\n```\n\n## Resources\n\n- https://web.dev/optimize-webfont-loading/\n- https://csswizardry.com/2020/05/the-fastest-google-fonts/\n- _(unmaintained)_ https://www.npmjs.com/package/webfontloader\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssninjastudio%2Funplugin-fonts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcssninjastudio%2Funplugin-fonts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssninjastudio%2Funplugin-fonts/lists"}