Skip to content
Edit on GitHub

Engines

The JS and WASM document engines, how GoTipe picks one, what needs WebAssembly and how the binary is loaded.

@gotipe/core@gotipe/wasmMIT

The engine holds the document, applies transactions and checks them against the schema. GoTipe has two implementations of one contract: a TypeScript engine inside @gotipe/core and a Rust engine compiled to WebAssembly in @gotipe/wasm. Both take the same document JSON and steps, count offsets in UTF-16 code units and use the same error codes, so you switch engines without changing your code. No behavioural differences are known in this release; see known differences.

Choose an engine

editor.ts
import { createEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";

const editor = await createEditor({ extensions: [DefaultPreset], engine: "auto" });
console.log(editor.engine); // "wasm" or "js"
Value Behaviour
"auto" (default) Loads the WASM engine. If the module can't be loaded, uses the JS engine and logs a warning.
"js" Uses the JS engine and never loads WebAssembly.
"wasm" Loads the WASM engine or rejects with WASM_INIT_FAILED.

"auto" falls back only when the module fails to load. An invalid schema or document fails with the same VALIDATION_ERROR in both engines; the editor does not retry it in the other one.

Entry points

Entry Engines References @gotipe/wasm
@gotipe/core auto, js, wasm Yes, through a dynamic import
@gotipe/core/js js only; engine: "wasm" rejects with WASM_INIT_FAILED No
@gotipe/core/server js only No

@gotipe/core/js exports the same API as @gotipe/core. Use it, or alias @gotipe/core to it, for a bundle without WebAssembly and a CSP without 'wasm-unsafe-eval'; see installation. PageEditor always runs on the JS engine.

What needs WebAssembly

Only collaboration. enableCollaboration, getCollaborationUpdate, receiveCollaborationUpdate and the providers in @gotipe/collaboration run on the Rust CRDT; on the JS engine they throw COLLABORATION_UNAVAILABLE. Create collaborative editors with engine: "wasm", so a missing module fails when the editor is created rather than later.

Editing, commands, history, Markdown, comments, suggestions, versions, AI and export work on both engines. PDF and DOCX export load their own module, @gotipe/export-wasm, which does not depend on the editor engine.

How the WASM engine runs a transaction: the TypeScript layer stages each transaction and validates it against the schema, then the Rust engine applies it. Markdown output uses the same TypeScript serializer for both engines. Undo history is kept by the editor in both; after enableCollaboration the CRDT owns it, so Undo reverts only local changes and keeps remote ones.

Loading the binary

The first createEditor call that needs WASM imports @gotipe/wasm. In the browser the module locates gotipe_wasm_bg.wasm with new URL(…, import.meta.url) and fetches it. In Node, which can't fetch a file: URL, the package's node export condition reads the binary from the installed package instead; browser bundles never include that entry. The module is loaded once per page or process; if loading fails, the next createEditor call tries again.

  • Your bundler must emit the .wasm file as an asset. Vite does in production builds; for its dev server, see installation.
  • Serve it as application/wasm.
  • Under a Content Security Policy, allow 'wasm-unsafe-eval' in script-src and the binary's URL in connect-src. See security.

Loading the binary yourself

createEditorWithLoader(options, loader) takes your own loader instead of the default one. Use it when the bundler can't emit the asset or when the binary lives on a CDN. With Vite, for example:

editor.ts
import { createEditorWithLoader, type WasmModuleLoader } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
import wasmUrl from "@gotipe/wasm/pkg/gotipe_wasm_bg.wasm?url";

const loadWasm: WasmModuleLoader = async () => {
  const wasm = await import("@gotipe/wasm");
  await wasm.default({ module_or_path: wasmUrl });
  return wasm;
};

const editor = await createEditorWithLoader(
  { extensions: [DefaultPreset], engine: "wasm" },
  loadWasm,
);

Pass null as the loader for a JS-only editor.

Known differences

None are known in this release.

Both engines add one to Document.version for every step they apply, as many as the transaction has; a rejected transaction leaves it as it was, and undo brings back the version from before the change. Listen to update to detect changes.

Both engines write the keys of block and mark attrs, and of objects inside them, in code point order, whatever order they were set in: the same document is the same getJSON() string on either engine and on every collaboration peer.

Both engines reject a step for a block that doesn't exist, and nothing of its transaction applies or enters the undo history:

  • deleteBlock, setBlockType, setBlockAttrs, removeMark and deleteText throw TRANSFORM_ERROR (Block not found: …);
  • insertText and addMark fail schema validation first, with VALIDATION_ERROR.

Sizes

CI fails a build that exceeds these budgets. JavaScript is measured as the summed gzip size of every file in the import graph. Adapter budgets exclude the core and the framework itself.

Part Budget, gzip
Core with the Markdown codec 125 KiB
@gotipe/react, on top of the core 40 KiB
@gotipe/vue, on top of the core 8 KiB
gotipe_wasm_bg.wasm 325 KiB

The WASM binary is about 826 KB before compression and 302 KB gzip; the budget leaves about 10% for growth. It comes in addition to the core JavaScript, which still provides the API, validation and Markdown. Details are in performance.