Aller au contenu

Web2js integration

TikZJax uses the sibling rod2ik/web2js project to build the browser TeX runtime.

Web2js is a build toolchain, not a runtime library imported directly by the TikZJax documentation.

Runtime artifacts

A successful Web2js build produces four runtime artifacts:

web2js/dist/tex.wasm
web2js/dist/tex.wasm.gz
web2js/dist/core.dump
web2js/dist/core.dump.gz

Their roles are:

File Role
tex.wasm Uncompressed WebAssembly TeX engine; useful for build validation and handoff integrity.
tex.wasm.gz Compressed WebAssembly runtime consumed by the TikZJax browser distribution.
core.dump Uncompressed preloaded TeX state; useful for validation and handoff integrity.
core.dump.gz Compressed preloaded TeX state consumed by the TikZJax browser distribution.

TikZJax keeps all four at the project root during local development. They are intentionally ignored by Git, but yarn zip includes them when they exist so a development ZIP represents the runtime that was actually tested.

TeX file manifest

Web2js also generates information about the TeX files needed by supported packages and TikZ libraries.

The deploy workflow merges generated entries into:

tikzjax/tex_files.json

TikZJax later uses yarn gen-tex-files / yarn build to generate the compressed runtime files under:

dist/tex_files/

Deploying Web2js to TikZJax

After changing Web2js:

cd ../web2js
yarn bfc
yarn deploy:tikzjax

yarn deploy:tikzjax performs both parts of the handoff:

  1. regenerates and merges the TeX-file manifest into TikZJax;
  2. copies tex.wasm, tex.wasm.gz, core.dump, and core.dump.gz from web2js/dist/ to ../tikzjax/.

Then validate TikZJax:

cd ../tikzjax
yarn bfc
yarn vendor:check
yarn dev

Why TikZJax rebuilds after a Web2js handoff

core.dump.gz, tex.wasm.gz, and tex_files.json are TikZJax build inputs.

When Web2js deploys new versions of them, the next yarn vendor:sync detects a different source hash and rebuilds TikZJax automatically.

If nothing changed, the next yarn dev skips the rebuild.

Verifying which TeX runtime is actually running

The TeX log contains the preloaded format date, for example:

preloaded format=latex 2026.8.21

This is useful when checking that the browser is using the newly deployed Web2js runtime rather than an older published npm/CDN release.

For local MkDocs development, browser assets should be loaded from paths such as:

/vendor/tikzjax/tikzjax.min.js
/vendor/tikzjax/run-tex.js

rather than from jsDelivr.

Publishing is intentionally different

The local Web2js handoff and the npm publication workflow are separate concerns.

The npm GitHub Actions workflow currently checks out the known-good rod2ik/cdn runtime and uses it during package publication. Do not assume that a local Web2js build is automatically published merely because it was deployed into a local TikZJax checkout.