Vendor system

The TikZJax documentation uses an explicit, incremental vendor system for local development.

Its goal is simple: the documentation should test the current local TikZJax build without rebuilding unrelated projects every time yarn dev is started.

Explicit whitelist

The configuration lives in:

vendor.config.mjs

Only projects listed in this file are considered vendors.

The synchronization code never scans the parent development directory such as ~/Documents/dev. A repository that happens to be next to TikZJax is ignored unless it is explicitly configured.

This is intentional: a development directory may contain many unrelated projects.

Generated vendor directory

The local documentation vendor is generated under:

site/overrides/vendor/<project>/

For TikZJax itself:

site/overrides/vendor/tikzjax/

This directory is disposable and ignored by Git.

The incremental state is also generated and ignored:

.cache/vendor-sync/state.json

Never maintain either location manually.

Incremental rebuild logic

For each configured project, vendor:sync computes a hash of the declared build inputs.

Conceptually:

configured source inputs
        │
        ▼
      hash
        │
        ├── same as previous run
        │       └── skip build
        │
        └── changed / cache absent / dist incomplete
                └── build project
                         │
                         ▼
                       dist/
                         │
                         ├── same as vendor → skip copy
                         └── different      → synchronize vendor

A documentation edit such as:

site/docs/examples/yquant.md

does not belong to the TikZJax build-input list, so it does not cause a JavaScript rebuild.

Current TikZJax inputs

The TikZJax vendor watches the files that can affect the generated distribution, including:

• src/;
• css/;
• fallback assets;
• tex_files.json;
• tikzlibraryarrows.meta.code.tex;
• build/generation scripts;
• webpack.config.cjs;
• package.json and yarn.lock;
• core.dump.gz and tex.wasm.gz.

The uncompressed Web2js files are inspected by vendor:check, but the browser build consumes the compressed runtime artifacts.

Why no automatic git pull?

The vendor workflow never updates a sibling Git working tree automatically.

A sibling project may contain:

• uncommitted work;
• a development branch;
• experiments that should not be replaced;
• a deliberately older checkout.

"Current local version" therefore means the code currently checked out on disk, not "whatever happens to be newest on the remote repository".

Checking state

Run:

yarn vendor:check

The command checks, for every configured vendor:

• source location and project version;
• whether required dist/ files exist;
• whether source inputs changed since the last synchronization;
• whether the vendor copy matches dist/;
• the four Web2js runtime handoff files and their SHA-256 hashes.

Cleaning state

yarn vendor:clean

This removes the generated vendor copy and the local incremental state. The next synchronization will recreate them.

Forcing a rebuild

For diagnosis only:

yarn vendor:sync --force

This bypasses the incremental source-hash optimization.

Adding another vendor

Add a new entry to the projects array in vendor.config.mjs.

A project entry declares four main things:

{
    name: 'example-project',
    local: '../example-project',
    dist: 'dist',
    build: {
        command: 'yarn',
        args: ['build']
    },
    inputs: [
        'src',
        'package.json',
        'yarn.lock'
    ],
    requiredDist: [
        'example.js'
    ]
}

The generic synchronization engine should not need to be rewritten for each additional project.

Choose inputs carefully: they should contain files that can change the generated dist/, not documentation or unrelated repository files.