Unifont

Common errors

• TypeError: (0 , unifont__WEBPACK_IMPORTED_MODULE_0__.createUnifont) is not a function

  cause Attempting to use Unifont (an ESM package) within a CommonJS environment, or incorrect bundler configuration.
  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.

• Error: Adobe provider requires 'id' option.

  cause The `providers.adobe()` function was called without the required `id` option.
  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.

• Error: Provider 'unknownProvider' not found.

  cause An invalid or unregistered provider name was passed to `createUnifont` or `unifont.resolveFont` options.
  fix Ensure you are using one of the built-in providers (e.g., `providers.google()`, `providers.adobe()`) or a correctly implemented custom provider.

Warnings

• breaking 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.
  Fix: Review font resolution configurations and explicitly request all desired variable font faces if they are not being loaded as expected.
• gotcha Unifont is an ESM-only package. Attempting to import it using CommonJS 'require()' syntax will result in runtime errors.
  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.
• gotcha 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.
  Fix: When initializing `providers.adobe()`, ensure you pass the `id` option, e.g., `providers.adobe({ id: process.env.ADOBE_KIT_ID ?? '' })`.
• gotcha 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.
  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.

Install

• npm install unifont npm
• yarn add unifont yarn
• pnpm add unifont pnpm

Imports

• createUnifont
  wrong:

  const { createUnifont } = require('unifont');

  correct:

  import { createUnifont } from 'unifont';

  Unifont is an ESM-only package. CommonJS 'require' syntax will not work.
• providers
  wrong:

  import providers from 'unifont';

  correct:

  import { providers } from 'unifont';

  The 'providers' object is a named export, not a default export.
• providers.google
  wrong:

  import { google } from 'unifont/providers';

  correct:

  import { providers } from 'unifont';
  const googleProvider = providers.google();

  Individual providers are accessed as properties of the 'providers' object.
• InitializedProvider

  import type { InitializedProvider } from 'unifont';

  Type imports for TypeScript users.
• ResolveFontResult

  import type { ResolveFontResult } from 'unifont';

  Type imports for TypeScript users, useful for destructuring results.

Quickstart

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.

import { createUnifont, providers } from 'unifont';

async function main() {
  // Initialize Unifont with one or more providers.
  // The Google Fonts provider is initialized without specific options here.
  const unifont = await createUnifont([
    providers.google(),
    providers.bunny(), // Adding another provider for a more robust example
  ]);

  // List all available fonts from the configured providers.
  console.log('Fetching available fonts...');
  const availableFonts = await unifont.listFonts();
  console.log('Available fonts:', availableFonts.slice(0, 5).map(f => f.name).join(', ') + '...'); // Log first 5 for brevity

  // Resolve a specific font family, e.g., 'Poppins'.
  // This will fetch the necessary font files and metadata.
  console.log('\nResolving "Poppins" font...');
  const { fonts: poppinsFonts, metrics: poppinsMetrics } = await unifont.resolveFont('Poppins');
  console.log('Resolved Poppins font files count:', poppinsFonts.length);
  // console.log('First Poppins font URL:', poppinsFonts[0]?.src); // Accessing the source URL for a resolved font

  // Example of resolving a font with specific options, like variable axis for Google Fonts
  // For Adobe Fonts, you would typically pass an ID: providers.adobe({ id: process.env.ADOBE_FONT_KIT_ID ?? '' })
  const { fonts: robotoFonts } = await unifont.resolveFont('Roboto Flex', {
    options: {
      google: {
        experimental: {
          variableAxis: {
            wght: [['100', '900']],
          },
        },
      },
    },
  });
  console.log('Resolved Roboto Flex (variable) font files count:', robotoFonts.length);
}

main().catch(console.error);