API · cpp.js · initCppJs

initCppJs(options?)

The cpp.js runtime factory. It instantiates the wasm module and resolves to the Module namespace, on which the GDAL classes and the runtime helpers live. initCppJs is cpp.js machinery, not gdal3.js: the same factory boots any cpp.js package.

Boot

boot

import "gdal3.js/Dataset.h";          // side-effect: register the classes
import "gdal3.js/Driver.h";
import "gdal3.js/GCP.h";
import "gdal3.js/SubdatasetInfo.h";
import { initCppJs, Gdal } from "gdal3.js/Gdal.h";

const Module = await initCppJs({ useWorker: true });
await Gdal.allRegister();             // register the driver set (once)

The side-effect .h imports register the embind classes (see Headers as modules); the entry header re-exports initCppJs. The factory returns the Module namespace, on which Gdal and the helpers live (Gdal is also reachable as Module.Gdal). Under useWorker the whole module is a Comlink proxy, so every call returns a promise.

Options

OPTION	TYPE	MEANING
`useWorker`	`boolean` (default `false`)	Browser only. Runs wasm in a Web Worker; the main thread gets a Comlink-bridged proxy, so every call returns a promise. Required for OPFS (the OPFS API is worker-scope only). Independent from threading.
`fs`	`{ opfs?: boolean }`	`opfs` defaults to true; pass `false` to mount only in-memory `/memfs`. OPFS actually activates only with `useWorker: true` and browser support, otherwise it falls back to `/memfs`. No effect outside the browser.
`env`	`Record<string, string>`	Environment variables for the wasm process. At runtime, values are strings; the literal token `_CPPJS_DATA_PATH_` is substituted with the data path (e.g. `{ TMPDIR: "_CPPJS_DATA_PATH_/scratch" }`). The function form of `env` is build-time (cppjs.config.js), not for runtime.
`logHandler` · `errorHandler`	`(text, channel) => void`	Replace the default stdout / stderr sinks (which log to `console`).
`onRuntimeInitialized`	`(Module) => void`	Called once the wasm runtime is ready; `Module.FS` and friends are valid here, not before.
`getWasmFunction`	`() => WebAssembly.Module`	Supply a precompiled module to bypass fetch-and-compile (zero network round-trip).
`workerUrl`	`string`	Override the worker script URL (defaults to what the bundler plugin set in `paths.worker`).
`paths`	`{ wasm?, data?, js?, worker? }`	Override individual asset URLs. The bundler plugin normally sets these.
`path`	`string`	A global URL prefix prepended to every asset.

Return value & lifecycle

initCppJs(opts) returns Promise<Module>. Embind exports from the bound C++ are attached as named members of Module (Gdal, Dataset, …); the cpp.js runtime helpers live there too. The init promise is cached, so calling initCppJs() again returns the same module.

initCppJs.terminate() (browser, useWorker) kills the worker and clears the cached promise, so the next initCppJs() re-instantiates.

Per-runtime notes

Browser. Multi-threading (a mt build) needs cross-origin isolation (COOP/COEP) in production; see workers & threading. OPFS needs useWorker: true.
Node. initCppJs() needs no options; GDAL works against the host filesystem.
Edge (e.g. Cloudflare Workers). initCppJs() only, in-memory: no useWorker, no OPFS, single-threaded.

← PREVSubdatasetInfo NEXT →Module helpers