# harfbuzzjs

harfbuzzjs Logo

[![Build](https://github.com/harfbuzz/harfbuzzjs/actions/workflows/build.yml/badge.svg)](https://github.com/harfbuzz/harfbuzzjs/actions/workflows/build.yml) [![NPM Version](https://img.shields.io/npm/v/harfbuzzjs)](https://www.npmjs.com/package/harfbuzzjs)
Providing [HarfBuzz](https://github.com/harfbuzz/harfbuzz) shaping library for client/server side JavaScript projects. See the demo [here](https://harfbuzz.github.io/harfbuzzjs/demo/). ## Download From the repo's [releases](https://github.com/harfbuzz/harfbuzzjs/releases), or npm: ``` npm install harfbuzzjs ``` ## Migrating from v0.x The v1 release introduced several API-breaking changes. See [MIGRATING](MIGRATING.md) for migrating from v0.x. ## Usage examples ```js 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](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](examples/harfbuzz.example.node.js). ## Development ### Building First install [emscripten](https://emscripten.org), 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](https://github.com/emscripten-core/emscripten/blob/master/tools/ports/harfbuzz.py) and [emscripten-ports/HarfBuzz](https://github.com/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.