--- title: Preferred JavaScript APIs description: Use portable browser and Node.js APIs for loading, writing, binary data, and images. hide_title: true page_style: designed --- import {DocPageHeader} from '@site/src/components/docs/doc-page-header'; import {DocOrientation, ReferenceBoundary} from '@site/src/components/docs/designed-doc'; loaders.gl supports input and output of data from JavaScript/TypeScript programs. To do this it is necessary to use platform APIs for - loading data from files and URLs - writing data to files - manipulating binary data - parsing images - etc Over the years, a number of different JavaScript APIs have emerged. Depending on the version of JavaScript supported by a browser or the version of Node.js being used. In addition, the set of available APIs move ## Loading data with `fetch()` loaders.gl standardizes on the `fetch()` API. The result of a `fetch` operation is a `Response` object which can be passed to many loaders.gl functions, meaning that the application can call `fetch()` itself to fully control the requests. :::info `fetch()` is available natively in browsers and all [supported Node.js versions](/docs/developer-guide/node#supported-nodejs-versions). ::: ## Local file access loaders.gl offers a `FileSystem`, `ReadableFile` and `WritableFile` interfaces, and various implementations of these. For local file access in the browser, the `File` class (a derivate of `Blob`, see below) is the tool of choice. Supported Node.js versions also provide the `File` class. > Note that reading local files in the browser has limitations. Actual file paths are obscured and files can only be created as a result of an interactive file selection or file drop action by the user. The preferred way to provide random-access data to loaders.gl is through `ReadableFile` implementations: - `HttpFile` reads from URLs and issues HTTP range requests when the server supports them. - `ArrayBufferFile` provides direct random access to an in-memory `ArrayBuffer` without a `Blob` conversion. - `BlobFile` wraps browser `Blob` and `File` instances and exposes efficient slicing. - `NodeFile` provides safe, tree-shakeable access to local files under Node.js without importing `fs` in application code. - `ArrayBufferFile` adapts in-memory buffers (such as data returned by `fetch`) to the same interface. `ReadableFile` classes replace the deprecated `FileProvider` utilities; new code should use the `ReadableFile` wrappers exported from `@loaders.gl/core/loader-utils` to keep loader interactions consistent across platforms. ### Validated HTTP ranges `HttpFile.open()` pins the remote object's byte length and available `ETag`/`Last-Modified` validators. Supplying identity from a trusted manifest avoids the opening one-byte probe: ```ts import {HttpFile} from '@loaders.gl/core/loader-utils'; const file = await HttpFile.open('https://example.com/data.parquet', { byteLength: manifest.byteLength, etag: manifest.etag, consistency: 'strict' }); const bytes = await file.read(offset, length, abortController.signal); console.log(file.getIdentitySnapshot(), file.getTelemetry()); ``` Every read requires an exact `206` response and validates `Content-Range`, response length, and the pinned object identity before returning bytes. `strict` consistency requires validators to remain visible; the default `best-effort` mode still rejects changed validators but permits servers whose CORS policy does not expose them. A shared `RangeRequestScheduler` can coalesce nearby reads while keeping different authentication and validator contexts isolated. ## Saving data Saving data from a browser is either done by POST requests to a server, or via local downloads. ## Binary data APIs The choice of binary data API in JavaScript usually comes down to either using Node.js `Buffer` class or a combination of `ArrayBuffer`, `TextEncoder`/`TextDecoder` classes. The `Buffer` class in Node.js is not supported by browsers. Polyfills are available, but they can add considerable size (~50KB) to an application, and can cause small but frustrating bundling issues. :::caution Therefore loaders.gl tries to avoid use of the `Buffer` class in its core libraries and loaders, preferring to use `ArrayBuffer`, typed arrays and `Blob`s. ::: `Blob` and `File` support partial, random-access reads from browser storage or local files. Both are available natively in [supported Node.js versions](/docs/developer-guide/node#supported-nodejs-versions). ## Image APIs The preferred image platform API is `ImageBitmap`. In browsers, loaders.gl uses the native `ImageBitmap` API when available. Under Node.js, importing `@loaders.gl/core/polyfills` installs a minimal `ImageBitmap` polyfill together with a global `getImageBitmapData(image)` helper so that `@loaders.gl/images` can keep using the same bitmap-oriented contract. This Node.js polyfill is intentionally limited. It is sufficient for loaders.gl image loading and `getImageBitmapData(image)`, but it does not provide a full browser-equivalent `createImageBitmap()` implementation.