harfbuzzjs

Providing HarfBuzz shaping library for client/server side JavaScript projects.

See the demo here.

Download

From the repo's releases, or npm:

npm install harfbuzzjs

Migrating from v0.x

The v1 release introduced several API-breaking changes. See MIGRATING for migrating from v0.x.

Usage examples

import * as hb from "harfbuzzjs";

// Load data from a font file:
const response = await fetch("font.ttf");
const arrayBuffer = await response.arrayBuffer();

// Create a HarfBuzz font object from the data:
const blob = new hb.Blob(arrayBuffer);
const face = new hb.Face(blob);
const font = new hb.Font(face);

// Shape text in a HarfBuzz buffer with the font:
const buffer = new hb.Buffer();
buffer.addText("abc");
buffer.guessSegmentProperties();
hb.shape(font, buffer);

// Enumerate the resulted glyphs in the buffer:
const infos = buffer.getGlyphInfos();
const positions = buffer.getGlyphPositions();
for (const [index, glyph] of infos.entries()) {
  const gid = glyph.codepoint; // Glyph ID despite the property name
  console.log(
    font.glyphToPath(gid), // SVG path
    positions[index], // xAdvance, yAdvance, xOffset, yOffset
  );
}

Alternative browser example

See examples/harfbuzz.example.html. To quickly run it in a browser:

npx http-server -o /examples/harfbuzz.example.html

Node.js example

See examples/harfbuzz.example.node.js.

Development

Building

First install emscripten, then:

make

Testing

make test

Need more of the library?

harfbuzzjs uses a stripped-down version of Harfbuzz generated by compiling Harfbuzz with -DHB_TINY. This may mean that some functions you need are not available. Look at src/harfbuzz-config.hh in the Harfbuzz source directory to see what has been removed. For example, HB_TINY defines HB_LEAN which (amongst other things) defines HB_NO_OT_GLYPH_NAMES. If, for example, you really need to get at the glyph names:

1. First, undefine the macro in question, by adding e.g. #undef HB_NO_OT_GLYPH_NAMES to config-override.h.
2. Next, export any function that you need by adding a line to harfbuzz.symbols; in this case _hb_ot_get_glyph_name.
3. Now the function will be exported through the WASM object, but you need to add TypeScript to bridge to it - in this case, handling the memory allocation of the char * parameter name and marshalling it to a JavaScript string. The best way to do this is to look at the source files in src/ for functions which use similar signatures.

If you have extended harfbuzzjs in ways that you think others will also benefit from, please raise a pull request. If there are parts of Harfbuzz that you need but the instructions above don't work, describe what you are trying to do in an issue.

Using the library in a bigger emscripten project?

See harfbuzz port inside emscripten and emscripten-ports/HarfBuzz, basically all you need is to use -s USE_HARFBUZZ=1 in your build.

binaryen

Optionally you can install binaryen and use wasm-opt like:

wasm-opt -Oz harfbuzz.wasm -o harfbuzz.wasm

binaryen also provides wasm-dis which can be used for,

wasm-dis harfbuzz.wasm | grep export
wasm-dis harfbuzz.wasm | grep import

with that you can check if the built wasm file only exports things you need and doesn't need to import anything, as usual with wasm files built here.