font-system0.4.5 • Public • Published
font-system is a font face compiler and optimizer that splits multiple fonts into separate unicode
codepoint ranges and creates applicable CSS
@font-face blocks for each.
The benefit of such a technique is smaller font download sizes, forcing the browser to only download parts of the fonts that are actually being used. This vastly simplifies internationalization (i18n) by removing the need to specify fonts alongside translations, and instead allows developers to specify a single font face that works across all languages in an efficient way.
Check out the
example/ directory to see a working
sample configuration, build script and test page.
You can either install
$ npm i -g font-system$ font-system --help
$ npm i --save-dev font-system$ ./node_modules/.bin/font-system --help
... or run it directly via
$ npm font-system --help
$ font-system [-hBUGDf] [-d display] [-b boldness] [-N boldness] [-p base_path] [-O name] -o output_dir/ config.json -h, --help Show this help message -o, --out-dir output_dir The directory in which font files and CSS are written (directory must exist) -B, --numeric-bold Don't use human-readable boldness, but instead numeric boldness -b, --bold boldness The weight class ("boldness") number to assign to boldness (default = 700) See NOTES about boldness. -N, --normal boldness The weight class ("boldness") number to assign to regular weighted fonts (default = 400) See NOTES about boldness. -p, --path base_path The base path for all fonts; the generated font base name is appended to this path -O, --out-name name The name of the generated .css file (without .css extension) (default = "fonts") -U, --unicode-ranges Use unicode ranges in the generated font files instead of the group numbers (more descriptive file names that are also much longer) -G, --no-groups Ignore the groupings specified by unicode-pages. This will generate more granular fonts but will require the browser makes more HTTP requests. -D, --display type Specifies a font-display value. Must be one of: auto, block, swap, fallback, optional -f, --fb-ranges Generate (potentially large) fallback font ranges based on which glyphs are available in the range. This will increase CSS size but eliminate any aggressive fallback font fetching.
font-system aims to be an all-in-one font compiler and optimizer for situations where multiple fonts are used to cover multiple languages (scripts).
To use font-system, pass a config.json file that contains a mapping of font face names to unicode script names (described below) to arrays of font files relative to the config.json's directory.
For example, the following config.json creates a CSS font face
MainTypeface (used by giving an element the CSS property
using the latin glyphs from the Roboto font and the cyrillic glyphs from
the PT Sans font. For any glyphs that aren't included in those ranges/fonts,
we've specified that the browser should fallback (
@) to the full fonts in the
latin group (meaning two sets of latin fonts are generated by font-system).
Script names are those defined as keys in the unicode-pages package.
All script names can either be an array of font paths relative to the config file (NOT the current working directory!) OR a single string referencing another script.
Recursive references are allowed, as long as they are not circular.
The fallback key (
@) indicates a font face that is used in the event
the browser cannot find a more specific font for a given glyph (specified
by the unicode glyph ranges belonging to any of the declared scripts).
While not explicitly mandatory, it is usually ideal to specify a base set of fonts with any extraneous glyphs. When in doubt, set this to match/reference your "latin" fonts.
In the case where
-B is not supplied, font-system will assign specific weight
classes ("boldness" numbers) a CSS-friendly weight.
For regularly weighted ("unweighted" or "unbolded") fonts, the CSS will simply
omit any bold specifiers. The default for this weight is 400 and can be overridden
For bold weighted fonts, the CSS will specify font-weight: bold for fonts with the specified
weight class. The default for this weight is 700 and can be overridden using
In all other cases, the numeric weight is specified with the font-weight property.
-B is supplied, the font weight number is specified for all fonts and no
human-readable font weight is used. The
-b flags are ignored when
-B is specified.
It's worth mentioning this utility was designed to work with the Google Font project, and makes a small number of assumptions about the fonts being loaded in. If you're seeing issues with a particular font, please open an issue at https://github.com/kor-tech/font-system.
Is it okay to use a synthetic/app-specific font family name?
Yes; it's even encouraged by the specification.
font-system is Copyright © 2019 by Kor Technologies. It is released under the MIT License.