Configuration
Two layers of configuration: how the module boots (initCppJs), and how GDAL behaves once it's running (config options).
Build-time configuration, the dependencies you include and the single vs multi-threaded target, lives in cppjs.config.js (see the Config reference); see Quick start and Workers. The rest of this page is the runtime side.
initCppJs options
const Module = await initCppJs({
useWorker: true, // run GDAL in a Web Worker (browser)
fs: { opfs: true }, // OPFS-backed VFS (the default in worker mode)
});| OPTION | DEFAULT | WHAT IT DOES |
|---|---|---|
useWorker | false | Boots the wasm module inside a Web Worker and returns proxied objects, so conversions never block the UI thread. See workers. |
fs.opfs | true | On by default in worker mode: backs the virtual FS with the Origin Private File System at /opfs (persists across reloads). Needs useWorker + browser OPFS support; pass false for in-memory /memfs. See VFS. |
On Node and React Native, initCppJs() needs no options. GDAL works against the host filesystem.
GDAL config options
Anything you'd set with --config KEY VALUE on the CLI is available at runtime:
await Gdal.setConfigOption("OGR_ORGANIZE_POLYGONS", "SKIP"); // issue #101's fix
await Gdal.setConfigOption("OSM_USE_CUSTOM_INDEXING", "NO"); // issue #87's fix
const v = await Gdal.getConfigOption("OGR_ORGANIZE_POLYGONS", "");Related calls, straight from the bound GDAL API: setThreadLocalConfigOption, getGlobalConfigOption, getConfigOptions, and path-scoped variants (setPathSpecificOption, getPathSpecificOption, clearPathSpecificOptions). The full catalogue of keys is in the GDAL configuration options documentation.
Driver-specific open options (the CLI's -oo) go through Gdal.openEx(path, flags, allowedDrivers, openOptions, siblingFiles) instead.
Raster block cache
await Gdal.setCacheMax(64 * 1024 * 1024); // bytes
const used = await Gdal.getCacheUsed();
const max = await Gdal.getCacheMax();GDAL's raster block cache trades memory for speed. In memory-constrained tabs (mobile browsers especially), lowering it helps. See memory.