# How Supersplat Handles Version Compatibility Checks Between Dependencies

> Discover how Supersplat ensures dependency version compatibility using npm's package management exact version pins peer dependencies and engine constraints for secure installations and builds.

- Repository: [PlayCanvas/supersplat](https://github.com/playcanvas/supersplat)
- Tags: internals
- Published: 2026-05-10

---

**Supersplat enforces version compatibility through npm's standard package management system, using exact version pins in [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json), peer-dependency declarations, and engine constraints to validate dependencies during installation and build time.**

The Supersplat project from `playcanvas/supersplat` manages its JavaScript dependency graph through strict manifest-driven constraints rather than custom runtime validation. This approach ensures that **version compatibility checks** occur during `npm install` and the Rollup bundling phase, preventing version-related failures before the application launches.

## Manifest-Driven Version Compatibility Checks

The repository's [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) serves as the single source of truth for dependency compatibility. Rather than implementing manual runtime checks, Supersplat relies on npm's built-in semver resolution to enforce constraints before the code executes.

### Exact Version Pinning

Most direct dependencies in [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) use **fixed versions** to eliminate runtime surprises. For example, the manifest pins `"playcanvas": "2.18.1"` and `"@playcanvas/splat-transform": "2.1.0"`. This guarantees that the code runs against a known, tested version of each library.

```json
{
  "name": "supersplat",
  "version": "2.25.1",
  "engines": {
    "node": ">=20.19.0"
  },
  "dependencies": {
    "playcanvas": "2.18.1",
    "@playcanvas/splat-transform": "2.1.0"
  },
  "peerDependencies": {
    "some-lib": "^1.4.0"
  }
}

```

### Peer-Dependency Requirements

The [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) lists several `peerDependencies` that specify version ranges for libraries Supersplat expects the host environment to provide, such as `playcanvas` and `@playcanvas/splat-transform`. During `npm install`, npm validates that resolved versions satisfy these declared ranges by checking against the constraints recorded in [`package-lock.json`](https://github.com/playcanvas/supersplat/blob/main/package-lock.json).

### Node.js Engine Constraints

The `"engines"` field enforces a minimum Node.js version: `"node": ">=20.19.0"`. This ensures that language features and underlying APIs remain compatible across development and production environments.

## Build-Time Validation of Dependencies

The project's build scripts provide an additional safety net beyond npm's installation checks. The `"build": "rollup -c"` script in [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) invokes Rollup using [`rollup.config.js`](https://github.com/playcanvas/supersplat/blob/main/rollup.config.js), which resolves imports according to the version graph that npm produces during installation.

If a version mismatch slipped through the install step, Rollup would fail to locate a module or emit duplicate bundles, catching inconsistencies before deployment. Source files like [`src/scene.ts`](https://github.com/playcanvas/supersplat/blob/main/src/scene.ts) and [`src/transform.ts`](https://github.com/playcanvas/supersplat/blob/main/src/transform.ts) rely entirely on these manifest guarantees and contain no additional runtime version checks.

```ts
// Example: Importing a peer-dependency – the version is already validated by npm
import { Splat } from '@playcanvas/splat-transform';

// The code can safely assume the API matches the version range declared in package.json
const splat = new Splat();
splat.load('model.splat');

```

## Installation-Time Verification

When installing Supersplat, npm automatically verifies all version constraints defined in [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) and locked in [`package-lock.json`](https://github.com/playcanvas/supersplat/blob/main/package-lock.json). The lock file records exact versions and lists all peer-dependency ranges used during resolution.

```bash

# Install Supersplat – npm will verify all version constraints

npm ci   # uses package-lock.json to enforce exact versions

# or

npm install   # checks peerDependency ranges and prints warnings if they are violated

```

Because Supersplat does not contain custom runtime version-checking code, all compatibility enforcement happens **before** the application is built or launched.

## Summary

- **Manifest-driven enforcement**: Supersplat uses [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) to declare exact versions, peer-dependency ranges, and Node.js engine requirements.
- **Pre-build validation**: npm checks version constraints during installation, while Rollup acts as a secondary safety net during bundling.
- **Fixed version pins**: Direct dependencies use exact versions like `"playcanvas": "2.18.1"` to ensure tested compatibility.
- **No runtime checks**: Source files in `src/` rely on npm's resolution guarantees rather than implementing custom version validation logic.

## Frequently Asked Questions

### How does Supersplat handle version mismatches during installation?

npm validates all `peerDependencies` and exact version pins when you run `npm install` or `npm ci`. If a peer-dependency version falls outside the declared range (e.g., `^1.4.0`), npm aborts the installation or prints a warning. The [`package-lock.json`](https://github.com/playcanvas/supersplat/blob/main/package-lock.json) file ensures that `npm ci` enforces the exact versions tested by the maintainers.

### Why doesn't Supersplat include runtime version checks?

The project delegates all version compatibility checks to npm's package management system and the Rollup bundler. Since dependencies are resolved and validated during the installation and build phases, runtime checks would be redundant. This design keeps the source code clean and avoids performance overhead in the production bundle.

### What happens if a dependency version is incompatible during the build?

If a version mismatch slips past npm's installation checks, the Rollup bundler (configured in [`rollup.config.js`](https://github.com/playcanvas/supersplat/blob/main/rollup.config.js) and invoked via `"build": "rollup -c"`) will fail to resolve the import or generate duplicate bundles. This build-time failure prevents the deployment of incompatible dependency combinations. The build script processes source files like [`src/scene.ts`](https://github.com/playcanvas/supersplat/blob/main/src/scene.ts) and [`src/transform.ts`](https://github.com/playcanvas/supersplat/blob/main/src/transform.ts), which assume all imported modules match the versions declared in [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json).

### Which file controls the minimum Node.js version for Supersplat?

The [`package.json`](https://github.com/playcanvas/supersplat/blob/main/package.json) file contains an `"engines"` field that specifies `"node": ">=20.19.0"`. This constraint forces Supersplat to run only on Node.js 20.19.0 or higher, ensuring compatibility with modern JavaScript features and APIs used throughout the codebase.