@eloraa/font-loader
v1.0.13
Published
Load local font
Downloads
214
Maintainers
eloraaReadme
@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-devor
pnpm add -D @eloraa/font-loaderCLI (Recommended)
To generate a configuration file, run the following command:
npx @eloraa/font-loader generateor
pnpm dlx @eloraa/font-loader generateThis 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-loaderor
pnpm add -g @eloraa/font-loaderAfter installation, you can run:
font-loader processIf you prefer not to install it globally, you can continue using npx or pnpm dlx:
npx @eloraa/font-loader processor
pnpm dlx @eloraa/font-loader processUsing 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 (
stringorstring[]): 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 (
stringorstring[]): 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).
Contribution
Contributions will be appreciated! To get started:
- Fork the repository on GitHub.
- Clone your fork locally.
- Create a new branch for your feature or bug fix.
- Make your changes and commit them.
- Submit a pull request.
License
This project is licensed under the MIT License.