Web quickstart

The SDK is the engine as a package for your own code. It's one WebAssembly file, engine.wasm, with a small JavaScript layer around it. WebAssembly is compiled code that browsers and Node run at close to native speed, so the engine works on your users' devices with no server of ours involved.

1. Tell npm where the package is

The SDK isn't on the public npm registry. It comes from Typomat's own, which asks for your download token. Make a file called .npmrc in your project folder, with these two lines:

@typomat:registry=https://engine.typomat.app/api/npm/
//engine.typomat.app/api/npm/:_authToken=${TYPOMAT_TOKEN}

The first line sends every @typomat package to Typomat's registry. The second reads your token from an environment variable called TYPOMAT_TOKEN, so the token itself never goes into your repository. It's a secret: keep it in your environment, or in your build server's secrets.

2. Install the package

TYPOMAT_TOKEN=tm_dl_... npm install @typomat/engine

What you should see: npm says it added a package, and your project now has node_modules/@typomat/engine. If it answers 401, the token is missing or wrong: check the TYPOMAT_TOKEN part of the command. A 403 means the licence behind the token isn't active, and the message says what to do.

3. Compile a font

Save this as make-font.mjs in your project folder. The .mjs ending tells Node the file uses import.

import { writeFile } from "node:fs/promises";
import { createEngine } from "@typomat/engine";

// Load the engine once. Without a key it runs in evaluation mode.
const engine = await createEngine({ licenseKey: process.env.TYPOMAT_LICENSE });

// A few parameters, and a name for the font. Anything left out stays at its default.
const font = engine.compile(
  { weight: 118, contrast: 0.92, serif: 0.5, xHeight: 470 },
  { name: "Acme Display" },
);

await writeFile("acme-display.ttf", font);
console.log(engine.license.mode, font.length, "bytes");

Run it, with your licence key if you have one:

TYPOMAT_LICENSE=TM2... node make-font.mjs

What you should see: a new file, acme-display.ttf, about 54 KB with a licence key. Open it with your computer's font viewer to see the letters. Without a key, Node first prints a note that the engine is in evaluation mode, and the font holds the letters only. Both are expected.

compile gives back the font file's bytes, as a Uint8Array. That's TrueType, which people install on their computers. For a web page, ask for WOFF2, which is smaller: { name: "Acme Display", format: "woff2" }.

4. Show it in a web page

The same code runs in a browser. There, you don't write a file: you hand the bytes to the page as a FontFace, and the text changes to the new font.

import { createEngine } from "@typomat/engine";

const engine = await createEngine({ licenseKey: "TM2..." });
const font = engine.compile({ weight: 118, contrast: 0.92 }, { name: "Acme Display", format: "woff2" });

const face = new FontFace("Acme Display", font);
document.fonts.add(await face.load());
document.body.style.fontFamily = "Acme Display";

This needs a bundler: the tool that packs your JavaScript for the browser, such as Vite or webpack. Both find engine.wasm in the package and ship it with your page by themselves. If yours doesn't, copy node_modules/@typomat/engine/engine.wasm to your site and pass its address as wasm, as the JavaScript SDK reference shows.

What you should see: the page's text in the new font, a moment after it loads. The licence key is fine in a browser: it isn't a secret, and it only works for what it names. On a licence for one website, localhost always works, so you can try it before you deploy.

5. Keep the page smooth

A whole font takes about 315 ms. That's fine for one font, but too long to block the page while someone drags a slider. The package has a second entry, @typomat/engine/worker, with the same methods running in a worker: a background thread of the browser's, so the page never waits. Font controls on the web shows it step by step.