How Supersplat Handles Version Compatibility Checks Between Dependencies

Supersplat enforces version compatibility through npm's standard package management system, using exact version pins in 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 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 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.

{
  "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 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.

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 invokes Rollup using 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 and src/transform.ts rely entirely on these manifest guarantees and contain no additional runtime version checks.

// 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 and locked in package-lock.json. The lock file records exact versions and lists all peer-dependency ranges used during resolution.

# 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 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 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 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 and src/transform.ts, which assume all imported modules match the versions declared in package.json.

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

The 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}