How fonts are chosen
The layout asks a font registry for each family name in the document (Calibri, Times New Roman …). The registry gives a face, or a fallback.
The library ships a portable profile in @reductoai/portable-fonts. It has open fonts with the same metrics as the Office fonts:
Plus script fallbacks: Droid Sans Fallback for Chinese, Japanese and Korean, and a Noto face for each other script Word sets outside its Latin fonts (Arabic, Hebrew, Indic scripts, Thai, Lao, Khmer, Myanmar, Tibetan, Georgian, Armenian, Ethiopic and others). Greek and Cyrillic in a clone with no Greek or Cyrillic (Caladea, Gelasio, Selawik) take Times New Roman’s or Arial’s clone. These faces do not have the metrics of Word’s own script fonts, so lines in those scripts can break in other places.
Selawik has no italic face, so Segoe UI italic is the upright face, slanted. A font with no clone (Aptos, Verdana, Tahoma) takes the face Word gives a missing font: Calibri’s clone for most sans fonts, Cambria’s for serif fonts.
The licences are in the package:
LICENSE.md, OFL-Gelasio.txt, OFL-Selawik.txt, OFL-Noto.txt and DROID-NOTICE.
Node
@reductoai/docx/node registers fonts the first time it lays out a document:
- If
DOCX_FONT_MIRRORis set, it uses the portable profile plus the faces in that folder. The folder must contain afont-table.json(see below). - Else, on a Mac with the Office fonts installed, it uses those fonts. This gives the closest match to Word.
- Else (Linux servers, CI), it uses the portable profile and writes one warning:
Use your own fonts on a server
For the document server, see Document server fonts: it reads a folder of font files and needs nofont-table.json.
If you have a license for the Office fonts, put them in a folder with a font-table.json:
DOCX_FONT_MIRROR=/path/to/folder.
The engine reads that folder once, when it loads. To lay out one document with other faces, give runPipeline or convertDocxToPdf a measurer whose FontRegistry has them (registerFontFile, registerBuiltinFamilies). That document then lays out with the registry’s faces and nothing else. A registry that adds no faces, such as the default one or registerPortableFonts alone, keeps the engine’s shared table at no extra cost.
WordDocument takes no measurer: register the faces on defaultFontRegistry (from @reductoai/docx) before you open the document. A document opened after that, and a runPipeline or convertDocxToPdf call without a measurer, lays out with them.
Browser
A page cannot read system fonts, so you give the layout a face provider. It downloads only the faces that a document uses, and only once.node_modules/@reductoai/portable-fonts/files to your static folder and point the URL there. Or serve them from the package with a route. In Next.js:
portableFaceProvider((file) => /fonts/${file}).
To serve other fonts, use tableFaceProvider(table, urlFor) with the same font-table.json format as DOCX_FONT_MIRROR.
Why layout runs twice
A face download is async, but layout is sync. SolayoutDocxInBrowser lays out once to find the faces the document needs, downloads them, and lays out again. When all faces are already in the cache, it lays out once. You do not need to do anything for this; it explains the first-load time.