init

<!-- GENERATED from docs/api/init.md by scripts/build-agent-skill.mjs. Do not edit. -->

`initNative(opts)` — Runtime API

The single entry point for calling into your Wasm module from JavaScript. Produced by the crossbind build pipeline; consumed by your application code.

> The same function is exported by browser, Node, and Edge runtime entries. The `opts` shape is identical; only the available *defaults* differ per runtime.

Where it comes from

With a bundler plugin (Vite, Rollup, Webpack, Rspack, Metro), import it from the header, `.rs` file, `cargo:` crate or `conan:` header you already import; every generated module exports the same function:

import { initNative } from './native/native.h';
import { initNative, Matrix } from './native/Matrix.h';
import { Uuid } from 'cargo:uuid';
import { zlibVersion } from 'conan:zlib/zlib.h';

await initNative();

One call binds every imported module: each proxy module registers its bindings when it is imported, and `initNative()` boots the runtime once and then resolves all of them. Node, Edge and standalone builds have no bundler plugin: there you import the built artifact directly and call its default export.

Those builds also write one ES module per runtime, `dist/node/napi.mjs` (`-e node` on darwin, linux, linuxmusl or win32), `dist/node/wasm.mjs` and `dist/edge/wasm.mjs` (the st-release wasm32 builds), that exports `initNative` and every bound name the same way. A package publishes them under paths of its own, and a standalone package as its root:

import { initNative, Matrix } from '@crossbind/example-lib-prebuilt-matrix/node/napi';
import { initNative as initZlib, crc32 } from '@crossbind/port-zlib-standalone-napi';

await Promise.all([initNative(), initZlib()]);

Signature

initNative(opts?: InitOptions): Promise<Module>

initNative.terminate(): void   // browser-only when useWorker:true

`Module` is the Emscripten runtime module enriched with crossbind helpers (see [§ Module helpers](#module-helpers) below).

`InitOptions`

{
  // ─────────────────────────────────────────────────────────────
  // Worker bridging (browser-only)
  // ─────────────────────────────────────────────────────────────
  useWorker: !!globalThis.Worker,
    // Defaults to ON wherever the Worker constructor exists, which is every
    // browser; pass false to keep the module on the calling thread. While it
    // is on, every call - construction included - resolves through the
    // bridge, so write `await new X(...)` and await the calls.
    //
    // When true, the Wasm module is instantiated inside a Web Worker
    // and the main-thread receives a Comlink-bridged proxy.
    //
    // REQUIRED for OPFS persistent storage: crossbind's OPFS backend
    // relies on synchronous access handles, which browsers expose only
    // in Worker scope; mounting /opfs/... from the main thread throws.
    //
    // Independent from threading: you can use `useWorker: true`
    // with `runtime: 'st'` and still get OPFS.
    //
    // NOT supported on edge runtimes (Cloudflare Workers, Deno
    // Deploy, Vercel Edge) — they don't expose the Worker API.

  workerUrl: undefined,
    // Override the worker script URL. Defaults to whatever the
    // bundler plugin set in config.paths.worker.

  // ─────────────────────────────────────────────────────────────
  // Filesystem
  // ─────────────────────────────────────────────────────────────
  fs: {
    opfs: true,
      // Browser default: true for a multithreaded build (runtime: 'mt'),
      // false for a single-threaded one. When false, only memfs is mounted.
      // Has no effect outside the browser.
      //
      // Even when true, OPFS only activates if:
      //   1. useWorker: true (Worker scope required), AND
      //   2. The browser supports OPFS (Chrome 86+, Firefox 111+,
      //      Safari 15.2+).
      //
      // If you mount /opfs/... but conditions aren't met, crossbind
      // logs an error and silently redirects the path to /memfs.
  },

  // ─────────────────────────────────────────────────────────────
  // Environment variables (passed to the Wasm process)
  // ─────────────────────────────────────────────────────────────
  env: {
    SOME_VAR: 'static-string',
    DATA_VAR: '_CROSSBIND_DATA_PATH_/myapp',
      // String values. They join the build-time env (targetSpecs[].specs.env
      // in crossbind.config.js, whose values may also be functions of
      // (state, target), see ADR-0003) and win over it key by key.
      //
      // Token replacement: the literal string `_CROSSBIND_DATA_PATH_`
      // inside any value is replaced with the runtime data path:
      // /crossbind in the browser and on the edge (the preloaded data),
      // the data directory next to the module in Node.js (`dataPath`
      // overrides it for a Node-API build).
  },

  // ─────────────────────────────────────────────────────────────
  // Logging hooks
  // ─────────────────────────────────────────────────────────────
  logHandler: undefined,
    // (text: string, channel: 'stdout') => void
    // Replaces the default `console.debug('wasm stdout: ...')`.

  errorHandler: undefined,
    // (text: string, channel: 'stderr') => void
    // Replaces the default `console.error('wasm stderr: ...')`.

  // ─────────────────────────────────────────────────────────────
  // Lifecycle
  // ─────────────────────────────────────────────────────────────
  onRuntimeInitialized: undefined,
    // (m: Module) => void
    // Called after the Wasm runtime finishes initializing.
    // Use this for post-init bootstrapping that needs `m.FS`, etc.

  // ─────────────────────────────────────────────────────────────
  // WebAssembly override
  // ─────────────────────────────────────────────────────────────
  getWasmFunction: undefined,
    // () => WebAssembly.Module
    // Bypass the default fetch-and-compile flow with a precompiled
    // module. Useful when you've embedded the .wasm via you