@reportwright/fonts-cjk

@reportwright/fonts-cjk (optional)

Chinese, Japanese, Korean and emoji fonts for ReportWright, downloaded on demand and checked by SHA-256.

Live demo: mrarun005.github.io/reportwright-demo (the gallery and the designer playground; the demo serves the bundled fonts, so CJK text there needs this package's files in its fontsUrl folder).

The fonts are Noto (SIL Open Font License). They are not in @reportwright/fonts because they are large:

File	Covers	Size
NotoSansJP.ttf	kana, Han (the default for Han text), CJK punctuation, full-width forms	9.6 MB
NotoSansKR.ttf	Hangul	10.4 MB
NotoSansSC.ttf	Simplified Chinese Han shapes (set fontFamily: "Noto Sans SC")	17.8 MB
NotoEmoji.ttf	emoji (monochrome)	2.0 MB
total		39.8 MB (the bundled fonts are 5.0 MB)

The package is small: the fonts are downloaded on demand (no install script runs), from google/fonts at a pinned commit, and each file is checked against its SHA-256 before it is written.

npm i @reportwright/engine @reportwright/fonts @reportwright/fonts-cjk
npx reportwright-fonts-cjk              # into the cache folder (below), where defaultFontStore() looks
npx reportwright-fonts-cjk public/pw/fonts/cjk   # or a folder you serve to the viewer (fontsUrl + cjk/)

import { fetchCjkFonts } from '@reportwright/fonts-cjk';
await fetchCjkFonts();                 // the same, from code (e.g. in your Docker build)

The fonts go to a cache folder outside node_modules, so upgrading or reinstalling the package keeps them:

	Folder
REPORTWRIGHT_FONTS_DIR set	that folder
XDG_CACHE_HOME set	$XDG_CACHE_HOME/reportwright/fonts-cjk
Windows	%LOCALAPPDATA%\reportwright\fonts-cjk
otherwise	~/.cache/reportwright/fonts-cjk

defaultFontStore() reads that folder first, then node_modules/@reportwright/fonts-cjk/fonts, where earlier versions downloaded them (so an existing install keeps working until its next upgrade). In a Docker image, set REPORTWRIGHT_FONTS_DIR for both the download step and the server, or run the download as the user the server runs as. cacheDir() and fontPath(name) give the folder and a downloaded file's path from code.

In the ReportWright app repository: npm run fonts:cjk (into public/fonts/cjk).

Licences: the fonts are SIL Open Font License 1.1 (OFL.txt is downloaded with them); the downloader is MIT.

The engine loads a face only when text needs it (FontStore asks for cjk/NotoSansJP.ttf through fontFile(key)), and a PDF embeds only the glyphs it uses: a line of Japanese, Korean and emoji adds about 8 KB. Without the files, those characters draw as boxes and the render warns how to add them. The fonts are variable fonts drawn at their default (regular) weight; bold CJK text is drawn regular.

Quick start (30 seconds)

After npx reportwright-fonts-cjk, CJK text renders with no other change:

import { render, defaultFontStore, exportPdf } from '@reportwright/engine';
const fonts = defaultFontStore();   // also reads the CJK cache folder
const def = { $schema: 'reportwright/report@1', name: 'Hello', page: { size: 'A4', margins: [36, 36, 36, 36] },
  sections: { body: { items: [{ type: 'textbox', name: 'Hi', x: 0, y: 0, w: 400, h: 24, value: 'こんにちは · 안녕하세요 · 你好' }] } } };
const pdf = await exportPdf(await render(def, { fontStore: fonts }), { fonts });

Verified against this version in Node 20 (Japanese, Korean and Simplified Chinese; the emoji download returned HTTP 504 from the upstream host on the day it was checked, and the command stops at the first failed file).

Examples

Docker image: download at build time into a fixed folder the server also reads.

ENV REPORTWRIGHT_FONTS_DIR=/opt/reportwright/fonts
RUN npx reportwright-fonts-cjk

Simplified Chinese shapes instead of the default (Japanese) Han shapes: "style": { "fontFamily": "Noto Sans SC" }.

Browser viewer: download into the served fonts folder, under cjk/: npx reportwright-fonts-cjk public/pw/fonts/cjk with fontsUrl: '/pw/fonts/'.

API

Export	What
fetchCjkFonts(dir?, { log?, fetch? })	downloads and checks every file into dir (default cacheDir())
cacheDir(env?, platform?, home?)	the folder the fonts go to (rules below)
fontPath(name)	a downloaded file's path
CJK_FONTS	the files: upstream path, file name, SHA-256
CLI reportwright-fonts-cjk [dir]	fetchCjkFonts from the command line

Requires Node 20.9 or later (it uses the global fetch). Related: @reportwright/fonts (the bundled fonts), @reportwright/engine, @reportwright/viewer.