@eloraa/font-loader NPM

@eloraa/font-loader

@eloraa/font-loader is a TypeScript package designed to simplify self-hosting fonts and generating CSS for them. Inspired by the next/font package, it offers self-hosting for any font file. This enables optimal font loading with zero layout shift, utilizing the CSS size-adjust property.

Installation

You can install the package using either npm or pnpm:

npm install @eloraa/font-loader --save-dev

pnpm add -D @eloraa/font-loader

CLI (Recommended)

To generate a configuration file, run the following command:

npx @eloraa/font-loader generate

pnpm dlx @eloraa/font-loader generate

This will create a default config file (font.config.js or font.config.cjs based on the environment) in your project.

Once the config is generated, you can add a script to your package.json to process fonts:

{
  "scripts": {
    "generate:font": "font-loader process"
  }
}

Alternatively, you can install @eloraa/font-loader globally using npm or pnpm:

npm install -g @eloraa/font-loader

pnpm add -g @eloraa/font-loader

After installation, you can run:

font-loader process

If you prefer not to install it globally, you can continue using npx or pnpm dlx:

npx @eloraa/font-loader process

pnpm dlx @eloraa/font-loader process

Using the Generated CSS

Once the CSS file is generated, you can include it in your project in one of the following ways:

1. Import in JavaScript/TypeScript:

import 'path/to/style.css';

2. Add a `<link>` tag in your HTML:

<link rel="stylesheet" href="path/to/style.css" />

There are other ways to include the generated CSS in your project, but this is the most common.

Browser API (Not Recommended)

While @eloraa/font-loader provides a browser API, it is less efficient and limited compared to the Node.js and CLI versions. If you cannot use Node.js in your project, consider using the CLI tool.

Using the Browser API:

import { localFont } from '@eloraa/font-loader/browser';

const font = localFont({
  src: '/path-to-your-font-file.ttf',
  display: 'swap',
});

Note: The browser API appends a <link> tag with the generated CSS to the <head> of the document and cannot write files directly.

Node.js API

Note: For most use cases, the Node.js API is the most flexible and powerful. However, it is intended to run only in a Node.js environment. If you attempt to use it in a browser, it will throw errors. If you need to use font loading functionality in a browser, please use the browser API provided by @eloraa/font-loader/browser (not recommended).

Example Usage:

import { localFont } from '@eloraa/font-loader';

const font = localFont({
  src: './path-to-your-font-file.ttf',
  outputCss: 'fonts.css', // optional, generates [hash].css by default
  display: 'swap',
  weight: '400', // optional
  style: 'normal', // optional
});

Node.js API Options

src (string or string[]): The source of the font file. Can be a single file or an array of font files with specific weights and styles.
outputDir (string): Directory to save the font files (default: './fonts').
outputCss (string): The name of the CSS file to generate.
appendTo (string): Path to an existing CSS file to append the generated CSS to.
display ('auto' | 'block' | 'swap' | 'fallback' | 'optional'): CSS font-display value (default: 'swap').
weight (string): Font weight (optional, e.g., '400', 'bold').
style (string): Font style (optional, e.g., 'normal', 'italic').
adjustFontFallback ('Arial' | 'Times New Roman' | false): Adjust fallback font metrics (default: 'Arial').
fallback (string[]): Array of fallback fonts.
preload (boolean): Preload the font (optional).
variable (string): CSS variable to use for the font (optional).

Example with Multiple Fonts

import { localFont } from '@eloraa/font-loader';

const font = localFont({
  src: [
    { path: './path-to-your-regular-font.ttf', weight: '400' },
    { path: './path-to-your-bold-font.ttf', weight: '700' },
  ],
  outputCss: 'my-fonts.css',
  display: 'swap',
  preload: true,
  variable: '--my-font-variable',
});

This will create a CSS file (my-fonts.css) with the appropriate @font-face declarations for each font file. The font can then be used via the generated CSS class or variable.

API

`localFont(options)`

The localFont function accepts an object with the following properties:

src (string or string[]): The source of the font file. Can be a single file or an array of font files with specific weights and styles.
outputDir (string): Directory to save the font files (default: './fonts').
outputCss (string): The name of the CSS file to generate.
appendTo (string): Path to an existing CSS file to append the generated CSS to.
display ('auto' | 'block' | 'swap' | 'fallback' | 'optional'): CSS font-display value (default: 'swap').
weight (string): Font weight (optional, e.g., '400', 'bold').
style (string): Font style (optional, e.g., 'normal', 'italic').
adjustFontFallback ('Arial' | 'Times New Roman' | false): Adjust fallback font metrics (default: 'Arial').
fallback (string[]): Array of fallback fonts.
preload (boolean): Preload the font (optional).
variable (string): CSS variable to use for the font (optional).