glb-compressor Library

Programmatic API for multi-phase GLB/glTF compression. Skinned-model-aware pipeline with gltfpack-first strategy and meshopt WASM fallback.

Quick Start

import { compress, init, PRESETS } from 'glb-compressor';

await init(); // Pre-warm WASM (optional, called automatically)
const glbBytes = await Bun.file('model.glb').bytes();
const result = await compress(glbBytes, { preset: 'aggressive' });
await Bun.write('out.glb', result.buffer);

Package Exports

import { ... } from 'glb-compressor';        // Library API
import { ... } from 'glb-compressor/server';  // Server (guarded by import.meta.main)
import { ... } from 'glb-compressor/cli';     // CLI entry

Conditional exports: "bun" field for Bun runtime, "node" for Node.js.

Core API

init(): Promise<void>

Pre-warm Draco + Meshopt WASM and configure glTF-Transform I/O. Called automatically by compress(), but can be called at boot to eliminate cold-start latency. Safe to call multiple times (shared promise).

compress(input, options?): Promise<CompressResult>

Main entry point. Runs the full 6-phase pipeline.

Parameters:

Returns: CompressResult

interface CompressResult {
	buffer: Uint8Array; // Compressed GLB binary
	method: string; // 'gltfpack' | 'meshopt'
	originalSize?: number; // Input byte count
}

getHasGltfpack(): boolean

Whether the gltfpack binary was found during initialization.

In This Reference

Reading Order

Pipeline Phases

1. Cleanup - dedup, prune, remove unused UVs (+ flatten/join/weld for static)
2. Geometry - merge by distance, remove degenerate faces, auto-decimate
3. GPU - instancing, vertex reorder, sparse encoding
4. Animation - resample keyframes, remove static tracks, normalize weights
5. Textures - compress to WebP via sharp (max 1024x1024)
6. Final - gltfpack (preferred) or meshopt WASM (fallback)

Skinned Model Awareness

When skins are detected, the pipeline automatically skips destructive transforms: flatten, join, weld, mergeByDistance, reorder, quantize, and auto-decimate. This prevents broken skeletons, weight denormalization, and mesh clipping.

Presets

type CompressPreset = 'default' | 'balanced' | 'aggressive' | 'max';

Anti-Patterns

• Don't flatten/join/weld/quantize skinned models.
• Don't import from cli/ or server/ - lib is the dependency root.
• Don't bypass mod.ts barrel for public API additions.