Runtimes
The same imports and the same API run everywhere. What changes per target is the platform package you install, where files live, how threading works, and how the library is delivered.
Capability matrix
| Runtime | Package(s) | Filesystem | Threading | Delivery |
|---|---|---|---|---|
| Browser | @gdal3.js/wasm |
OPFS · /vsimem/ · /vsizip/ |
Web Worker; multi-threaded with COOP/COEP, single-threaded otherwise | ESM / CJS, or UMD via @gdal3.js/wasm-bundle |
| Node.js | @gdal3.js/wasm |
Host filesystem (direct) | Single- or multi-threaded | ESM / CJS, or prebuilt @gdal3.js/wasm-bundle |
| React Native | @gdal3.js/android + @gdal3.js/ios |
Device filesystem (real paths) | Native threads | Native module over JSI |
| Edge (Cloudflare Workers) | @gdal3.js/wasm (single-threaded) |
In-memory only (/vsimem/) |
None (no SharedArrayBuffer) | Size-limited, see note |
GDAL reads and writes the same formats on every runtime; only persistence and parallelism differ. The complete file story is in the virtual filesystem guide; threading and the cross-origin-isolation headers are in workers & threading.
Browser
WebAssembly with an optional Web Worker (initCppJs({ useWorker: true })) so the UI never blocks. Files live in a virtual filesystem: write user data into OPFS (persists across reloads) or /vsimem/ (in-memory), then Gdal.openEx('/opfs/…'). Multi-threading needs cross-origin isolation; without it the single-threaded build runs anywhere. Wire it with the Vite, Webpack/Rspack or Rollup plugin.
Node.js
Same imports as the browser, but no virtual-FS hop: GDAL reads and writes the host filesystem directly, so Gdal.openEx('data/in.gpkg') just works. Bundle with the Rollup or Webpack plugin targeting Node, or use the prebuilt @gdal3.js/wasm-bundle.
React Native
Not wasm: GDAL runs as a real native library over JSI (New Architecture, Expo & bare). Install the native platform packages (@gdal3.js/android, @gdal3.js/ios) and the Metro/React-Native plugins (see Metro setup). Files use real device paths, no browser memory ceiling.
Edge (Cloudflare Workers)
The single-threaded wasm build runs on edge runtimes with an in-memory filesystem (no OPFS, no SharedArrayBuffer). One caveat: the full 189-driver build is large (≈14 MB gzipped) and exceeds Workers' bundle-size limits; a slimmer driver-subset build (@gdal3.js/wasm-bundle-minimal) for size-capped platforms is in progress.