@wllama/wllama-compat

Optional package that provides compatibility WASM assets for @wllama/wllama on browsers that lack JSPI or MEMORY64 support - most notably Safari and older browsers.

Why this package exists

The default @wllama/wllama build relies on two modern WebAssembly features: JSPI and MEMORY64

When either feature is absent, wllama automatically falls back to compat mode: a separate WASM build that uses Asyncify instead of JSPI, and drops MEMORY64.

Note: Compat mode has significantly lower performance than the default build. Use it only as a fallback.

Browser compatibility

| | Chromium | Firefox | Safari | |---|---|---|---| | Auto-compat (default, recommended) | ✅ | 🟡 (no WebGPU) | 🟡 (supports WebGPU) | | Force-compat | ✅ | 🔴 (supports WebGPU) | 🟡 (supports WebGPU) | | Non-compat mode | ✅ | 🟡 (no WebGPU) | ❌ |

• ✅: Good speed
• 🟡: Acceptable speed
• 🔴: Runs but slow, not usable
• ❌: Does not run at all

Default behaviour

Out of the box, wllama fetches the compat assets from jsDelivr CDN when compat mode is needed. If you want to self-host the assets (no external CDN dependency), install this package (see new section.)

Recommended preset

By default (mode = 'safari'), compat is disabled on Firefox because WebGPU via compat mode is extremely slow there. This is the recommended behaviour:

wllama.setCompat('default');

If you also want compat on Firefox (e.g. to reach users without JSPI enabled), pass 'firefox_safari':

wllama.setCompat('default', 'firefox_safari');

Disabling compat mode

To opt out of compat mode completely (e.g. you don't target Safari):

wllama.setCompat(null);

Using this package

You only need to install package if you want to store compat assets locally. By default, assets are pulled from CDN.

npm install @wllama/wllama-compat

Then copy the assets from node_modules/@wllama/wllama-compat/wasm/ to your public directory and call setCompat() with the URLs pointing to those files:

import { Wllama } from '@wllama/wllama';

const wllama = new Wllama({ default: '/wasm/wllama.wasm' });

wllama.setCompat({
  wasm: '/wllama-compat/wasm/wllama.wasm',
  worker: '/wllama-compat/wasm/wllama.js',
});

IMPORTANT: for Vite, you will need to import the JS as ?raw

import compatWasm from '@wllama/wllama-compat/wasm/wllama.wasm?url';
import compatWorker from '@wllama/wllama-compat/wasm/wllama.js?raw'; // IMPORTANT: ?raw, NOT ?url

export const WLLAMA_COMPAT_CONFIG = {
  wasm: compatWasm,
  worker: {
    code: compatWorker,
  },
};

const instance = new Wllama(WLLAMA_CONFIG_PATHS, { logger: DebugLogger });
instance.setCompat(WLLAMA_COMPAT_CONFIG);