gsplat.js: Install and render Gaussian Splats in JavaScript

gsplat.js for browser-based Gaussian Splatting

gsplat.js addresses a specific gap in browser graphics tooling: displaying 3D Gaussian Splatting data without writing a renderer around the Gaussian Splatting representation. It presents a JavaScript and TypeScript API with scene, camera, renderer, controls, and loader components, while also providing workflows for real-time updates, editing, file loading, scene transformations, and PLY conversion. The README describes it as offering functionality similar to three.js but for Gaussian Splatting.

The intended audience is a web developer already using ES6 modules and a bundler such as Vite. It is not positioned as a command-line reconstruction tool or a native 3D Gaussian Splatting training framework. The included examples are browser-facing and cover areas such as `examples/editor/`, `examples/file-loader/`, `examples/camera-updates/`, and `examples/scene-transformations/`.

The central format choice narrows the practical use case. A `.splat` file is a compact raw `Uint8Array` buffer intended to load faster than `.ply`. The cost is explicit: it does not contain spherical harmonics, or SH coefficients, so its colors are not view-dependent. That makes gsplat.js a reasonable choice for compact web visualization, but a questionable choice when appearance depends on directional lighting encoded by SH data.

The Scene, Loader, and WebGL render path

The documented rendering path is concrete and small. Application code creates a `SPLAT.Scene`, a `SPLAT.Camera`, and a `SPLAT.WebGLRenderer`. It creates `OrbitControls` with the camera and renderer canvas, loads data into the scene, and then schedules a `requestAnimationFrame` loop. Each frame updates the controls and calls `renderer.render(scene, camera)`.

The loader is asynchronous and receives a URL, the target scene, and a callback. In the README example, `SPLAT.Loader.LoadAsync(url, scene, () => {})` fetches the `.splat` data and associates it with the scene before rendering begins. The empty callback appears in the README example, but the documentation does not explain whether it reports progress, completion, or another loader event, so it should not be treated as a documented progress API.

The package is an ES module. Its `exports` map sends imports to `dist/index.es.js` and exposes TypeScript declarations through `dist/index.d.ts`. The build process also compiles WebAssembly with `compile_wasm.sh`, invokes Vite, and copies matching `.wasm` files from `src/wasm/` into `dist/wasm/`. The repository layout therefore confirms that the distributed package includes a WebAssembly build stage as well as the TypeScript API, although the README does not describe the internals of that WebAssembly component.

Installing gsplat.js in a Vite TypeScript project

The documented setup assumes Node.js, NPM, and an environment that supports ES6 modules. Create a Vite project with the `vanilla-ts` template. This command initializes the project directory used by the following installation steps.

npm create vite@latest gsplat -- --template vanilla-ts

Enter that directory, install its dependencies, and start its development server. The server should provide the Vite development output at its configured local address.

cd gsplat
npm install
npm run dev

Install gsplat.js as a saved NPM dependency from inside the project.

npm install --save gsplat

The package name is `gsplat`, while the repository and documentation use the name `gsplat.js`. Consumers should import the published package as `gsplat`. The current package metadata identifies version `1.2.9`, exposes ES module output, and declares MIT licensing. The repository is not archived, and its last push was on 2026-09-24, which indicates recent repository activity. That does not by itself establish compatibility stability for every browser or splat format.

Loading Bonsai data and starting the render loop

Place the first scene objects in `src/main.ts` when following the Vite setup. These declarations establish the scene graph target, camera, WebGL renderer, and controls.

import * as SPLAT from "gsplat";

const scene = new SPLAT.Scene();
const camera = new SPLAT.Camera();
const renderer = new SPLAT.WebGLRenderer();
const controls = new SPLAT.OrbitControls(camera, renderer.canvas);

The following example loads the documented Bonsai `.splat` URL. Loading is awaited before the render loop starts, and each animation frame updates controls and renders the scene.

async function main() {
    const url = "https://huggingface.co/datasets/dylanebert/3dgs/resolve/main/bonsai/bonsai-7k.splat";

    await SPLAT.Loader.LoadAsync(url, scene, () => {});

    const frame = () => {
        controls.update();
        renderer.render(scene, camera);

        requestAnimationFrame(frame);
    };

    requestAnimationFrame(frame);
}

main();

This is the first useful deployment test because it exercises module imports, remote data access, loader integration, canvas creation, and continuous rendering. It does not show local file selection, loading progress, resize handling, WebGL capability checks, or error handling. Those omissions matter for production use. The README's live demo also warns that it may not work on every device and recommends `Bonsai` for the lowest memory requirements.

Why `.splat` and PLY conversion trade fidelity for compact loading

The most important technical boundary is not the scene API but the data format. A `.splat` file is a compact representation made from a raw `Uint8Array` buffer. The README states that this compact form offers quicker loading than `.ply`, which can matter for browser delivery and interactive viewers. It also states that the format has no SH coefficients, making its colors non-view-dependent.

PLY is the real alternative data path. gsplat.js supports `.ply` files through the `examples/ply-converter/` workflow rather than presenting `.ply` and `.splat` as equivalent files. The converter changes `.ply` into `.splat` for the compact rendering path, and the example also contains commented code for converting in the other direction. The difference is semantic rather than cosmetic: once SH coefficients are discarded by a `.ply` to `.splat` conversion, converting back to `.ply` cannot restore them.

Choose `.splat` when compact browser loading matters more than view-dependent color. Choose a PLY-preserving workflow when the source dataset's SH data must survive conversion. The README does not state that `Loader.LoadAsync` reads PLY directly, so application authors should not infer that capability from the existence of the PLY converter. It provides conversion examples, and that is the specific PLY support described.

Production limits in memory, tests, and error handling

Browser support is the first limitation. The README says the live viewer may not work on all devices, which is consistent with a WebGL renderer consuming substantial GPU and system resources for large Gaussian datasets, although the project does not publish device requirements or numerical memory limits. It points specifically to the Bonsai demo as the lowest-memory option. Teams should therefore check their actual dataset and target devices rather than infer capacity from the API example.

The package also defines `npm test` as a command that prints `No tests specified` and exits successfully. That means the published package metadata does not identify an automated test suite through the standard test command. A successful `npm test` invocation therefore does not demonstrate renderer, loader, conversion, or browser compatibility. The available `lint` and `format` scripts cover TypeScript source and examples, but static checks do not replace runtime validation.

Error behavior is not documented in the README. The example supplies an empty loader callback and does not show a `catch` block for the URL load, WebGL initialization, context loss, or animation-loop failures. The source may contain implementation behavior beyond the examples, but it cannot be confirmed from the documented API. This makes error paths an explicit area to verify before adopting the library in an application where a failed scene load must produce a recoverable user interface.

MIT library licensing and dataset provenance

The gsplat.js package is released under the MIT license. The README also identifies three.js, `antimatter15/splat`, and `UnityGaussianSplatting` as open-source projects on which it is built, listing each under the MIT license. The published JavaScript implementation therefore has a stated MIT licensing basis, subject to the actual license files and notices in any distributed dependency or build output.

There is a separate restriction relevant to adoption decisions. The README says the original 3D Gaussian Splatting research project uses a non-commercial license, even though gsplat.js provides an open-source rendering implementation. It explicitly instructs users to consider the source of splat data separately. This is not the same as saying that every `.splat` file inherits the research project's terms, nor does it provide a determination for a particular dataset.

For an engineer, the practical boundary is data provenance. Check the license attached to each training source, exported model, converted file, and hosted dataset rather than relying only on the renderer package's MIT label. The repository does not provide legal advice, and the README does not document automated license detection or validation of uploaded splat content.

Release and upgrade considerations for gsplat.js

The repository is not archived, and the last push was on 2026-09-24. The listed release history includes `1.2.8`, described as modern bundling and simplified loading, and `1.2.9`, described as a source map warning fix, both dated 2025-07-12. The package metadata currently reports version `1.2.9`. This record supports checking bundler and source-map behavior during upgrades, but it does not provide a published compatibility policy or migration guide for the loader and renderer API.

The package is organized as an ES module with generated declarations and distribution output. Applications that use a custom bundler should verify that its import handling matches the package `exports` configuration. The build also copies `.wasm` files into `dist/wasm/`, making deployment asset handling relevant even when application code imports only the root package. The README does not document CDN loading, CommonJS consumption, or hosting requirements for the WebAssembly files.

Version upgrades should therefore be treated as packaging changes that need application-level checks. The repository's examples cover several distinct behaviors, including file loading, camera updates, editing, transformations, frame-rate work, and PLY conversion. An upgrade should be checked against the particular example the application depends on, rather than against the package version number alone.

Editorial conclusion

gsplat.js is appropriate for browser developers who need a direct `.splat` loading path and can accept its WebGL rendering model and lack of spherical harmonics in that format. It is less suitable when view-dependent color fidelity requires preserved SH coefficients or when data provenance cannot be reviewed separately. Verify first that the chosen dataset loads at an acceptable memory cost on target devices, since the README specifically identifies the Bonsai demo as the lowest-memory option and does not document minimum hardware requirements.

Frequently asked questions

Official sources

1. huggingface/gsplat.js on GitHub
2. Issues
3. License: MIT
4. README
5. Releases