{"id":12283,"library":"unifont","title":"Unifont","description":"Unifont is a framework-agnostic JavaScript/TypeScript library designed to streamline access to font data from various Content Delivery Networks (CDNs) and font providers. It abstracts away the complexities of fetching and resolving fonts, supporting popular services like Google Fonts, Adobe Fonts, Bunny Fonts, Fontshare, and Fontsource. The library is currently at version 0.7.4 and maintains an active release cadence, frequently adding new provider features and addressing bug fixes, as seen in its recent updates like npm package resolution support and Adobe race condition handling. A key differentiator is its modular provider architecture, allowing users to integrate multiple font sources and even develop custom providers, simplifying font management and optimization across projects. It is an ESM-only package.","status":"active","version":"0.7.4","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/unifont","tags":["javascript","typescript"],"install":[{"cmd":"npm install unifont","lang":"bash","label":"npm"},{"cmd":"yarn add unifont","lang":"bash","label":"yarn"},{"cmd":"pnpm add unifont","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Unifont is an ESM-only package. CommonJS 'require' syntax will not work.","wrong":"const { createUnifont } = require('unifont');","symbol":"createUnifont","correct":"import { createUnifont } from 'unifont';"},{"note":"The 'providers' object is a named export, not a default export.","wrong":"import providers from 'unifont';","symbol":"providers","correct":"import { providers } from 'unifont';"},{"note":"Individual providers are accessed as properties of the 'providers' object.","wrong":"import { google } from 'unifont/providers';","symbol":"providers.google","correct":"import { providers } from 'unifont';\nconst googleProvider = providers.google();"},{"note":"Type imports for TypeScript users.","symbol":"InitializedProvider","correct":"import type { InitializedProvider } from 'unifont';"},{"note":"Type imports for TypeScript users, useful for destructuring results.","symbol":"ResolveFontResult","correct":"import type { ResolveFontResult } from 'unifont';"}],"quickstart":{"code":"import { createUnifont, providers } from 'unifont';\n\nasync function main() {\n  // Initialize Unifont with one or more providers.\n  // The Google Fonts provider is initialized without specific options here.\n  const unifont = await createUnifont([\n    providers.google(),\n    providers.bunny(), // Adding another provider for a more robust example\n  ]);\n\n  // List all available fonts from the configured providers.\n  console.log('Fetching available fonts...');\n  const availableFonts = await unifont.listFonts();\n  console.log('Available fonts:', availableFonts.slice(0, 5).map(f => f.name).join(', ') + '...'); // Log first 5 for brevity\n\n  // Resolve a specific font family, e.g., 'Poppins'.\n  // This will fetch the necessary font files and metadata.\n  console.log('\\nResolving \"Poppins\" font...');\n  const { fonts: poppinsFonts, metrics: poppinsMetrics } = await unifont.resolveFont('Poppins');\n  console.log('Resolved Poppins font files count:', poppinsFonts.length);\n  // console.log('First Poppins font URL:', poppinsFonts[0]?.src); // Accessing the source URL for a resolved font\n\n  // Example of resolving a font with specific options, like variable axis for Google Fonts\n  // For Adobe Fonts, you would typically pass an ID: providers.adobe({ id: process.env.ADOBE_FONT_KIT_ID ?? '' })\n  const { fonts: robotoFonts } = await unifont.resolveFont('Roboto Flex', {\n    options: {\n      google: {\n        experimental: {\n          variableAxis: {\n            wght: [['100', '900']],\n          },\n        },\n      },\n    },\n  });\n  console.log('Resolved Roboto Flex (variable) font files count:', robotoFonts.length);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to initialize Unifont with multiple providers, list available fonts, and resolve specific font families with optional configurations like variable axis settings for Google Fonts."},"warnings":[{"fix":"Review font resolution configurations and explicitly request all desired variable font faces if they are not being loaded as expected.","message":"Starting from v0.4.0, Unifont only downloads variable font faces when explicitly necessary. This change was implemented for optimization, but users might need to adjust their configurations if they previously relied on all variable font faces being downloaded by default.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Ensure your project is configured for ESM, typically by setting `\"type\": \"module\"` in `package.json` or using `.mjs` file extensions, and use `import` statements.","message":"Unifont is an ESM-only package. Attempting to import it using CommonJS 'require()' syntax will result in runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When initializing `providers.adobe()`, ensure you pass the `id` option, e.g., `providers.adobe({ id: process.env.ADOBE_KIT_ID ?? '' })`.","message":"The Adobe Fonts provider requires a kit `id`. Failing to provide this `id` will lead to resolution errors. It is strongly recommended to load this ID from environment variables for security and flexibility.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to v0.7.4 or later. For very high-concurrency scenarios, consider implementing custom retry logic or rate limiting around `unifont.resolveFont()` calls.","message":"While v0.7.4 includes a fix for race conditions with concurrent Adobe resolution, highly concurrent font fetching operations, especially with external providers, can still be prone to transient issues. Implement robust error handling and potentially introduce retries or rate limiting for critical paths.","severity":"gotcha","affected_versions":"<0.7.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project uses ES Modules (ESM). For Node.js, set `\"type\": \"module\"` in `package.json`. For bundlers, verify that your configuration supports ESM imports. Also, check for incorrect named vs default imports.","cause":"Attempting to use Unifont (an ESM package) within a CommonJS environment, or incorrect bundler configuration.","error":"TypeError: (0 , unifont__WEBPACK_IMPORTED_MODULE_0__.createUnifont) is not a function"},{"fix":"Pass the Adobe Fonts kit ID to the provider initialization: `providers.adobe({ id: 'your-adobe-kit-id' })`. It is recommended to load this from an environment variable.","cause":"The `providers.adobe()` function was called without the required `id` option.","error":"Error: Adobe provider requires 'id' option."},{"fix":"Ensure you are using one of the built-in providers (e.g., `providers.google()`, `providers.adobe()`) or a correctly implemented custom provider.","cause":"An invalid or unregistered provider name was passed to `createUnifont` or `unifont.resolveFont` options.","error":"Error: Provider 'unknownProvider' not found."}],"ecosystem":"npm"}