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:

| Param | Type | Description | | ----------------------- | ---------------- | -------------------------------------------------------- | | input | Uint8Array | Raw GLB file bytes | | options.preset | CompressPreset | 'default' | 'balanced' | 'aggressive' | 'max' | | options.simplifyRatio | number | Additional simplification in (0, 1) | | options.onLog | (msg) => void | Progress callback (used by SSE) | | options.quiet | boolean | Suppress console output |

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

| File | Purpose | | ------------------------------------------- | --------------------------------------------------- | | api.md | Full API surface: types, constants, utilities | | transforms.md | Custom glTF-Transform transforms for a-la-carte use |

Reading Order

| Task | Files to Read | | -------------------------- | ------------------------- | | Basic compression | This file only | | Custom pipeline / advanced | This file + transforms.md | | Full type reference | This file + api.md |

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';

| Preset | Skinned behavior | Static behavior | | ------------ | ------------------------------------------------- | --------------- | | default | -vp 20 -kn | -vp 16 | | balanced | + animation quant (-at 14 -ar 10 -as 14 -af 24) | Same + -vp 16 | | aggressive | + stronger quant (-at 12 -ar 8 -as 12 -af 15) | Same + -vp 14 | | max | + supercompression (-cz), simplify (-si 0.95) | Same |

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.