Manipulate glTF JSON in Node.js: Best NPM Packages

Manipulating glTF (GL Transmission Format) files programmatically is a common requirement for 3D asset pipelines, scene optimization, dynamic material swapping, and automated metadata insertion. This article reviews the primary npm packages available for Node.js to read, modify, and serialize glTF JSON structures efficiently, ranging from high-level graph-based abstractions to low-level JSON and buffer utilities.

1. @gltf-transform/core

@gltf-transform/core is part of the modular glTF-Transform library and is the standard modern tool for reading, editing, and writing glTF 2.0 and GLB files in Node.js.

  • How it works: It parses files into an in-memory graph structure called a Document. Instead of forcing developers to manage raw array indices and buffer byte offsets manually, it models nodes, meshes, materials, and textures as interrelated JavaScript objects.
  • Why use it: When you modify the structure (e.g., adding attributes or removing materials), the library automatically handles buffer reorganizations, accessor alignment, and index re-mapping when saving back to JSON or GLB.
  • Installation: npm install @gltf-transform/core

2. gltf-pipeline

Developed by Cesium, gltf-pipeline provides a dedicated Node.js API and command-line interface for deep content manipulation and optimization.

  • How it works: It processes glTF and GLB assets through modular stages. You can load a glTF file into an internal JSON representation alongside a dictionary of binary buffers.
  • Key capabilities: It excels at structural conversions—such as embedding binary data directly into JSON data URIs, extracting binary buffers into separate .bin files, and converting freely between .gltf and .glb.
  • Why use it: It is ideal for stage-based pipeline operations where you need to toggle between self-contained files and separate assets while applying automated structural changes.
  • Installation: npm install gltf-pipeline

3. @loaders.gl/gltf

Part of the Vis.gl framework ecosystem, @loaders.gl/gltf provides high-performance parsing and encoding for glTF and GLB formats.

  • How it works: It exposes functions such as parse and encode that handle both the JSON chunk and the binary chunks.
  • Key capabilities: For .glb files, it cleanly separates the JSON header chunk from binary chunks into a simple JavaScript object structure. This allows developers to read the JSON chunk, modify properties (like node hierarchies or extras objects), and repackage the chunks without decompressing or re-encoding geometric data.
  • Why use it: Best for applications already using the loaders.gl or deck.gl ecosystem, or for lightweight chunk-level inspection and manipulation.
  • Installation: npm install @loaders.gl/gltf @loaders.gl/core

4. Native fs with JSON.parse (Direct JSON Editing)

For non-binary .gltf files where the geometry is stored externally in separate .bin files, third-party libraries are not strictly necessary.

  • How it works: A .gltf file is a valid JSON document. You can read the file using Node’s native node:fs/promises, parse it with JSON.parse(), alter the data, and write it back using JSON.stringify().
  • Use case: This approach works well for simple edits, such as modifying the asset.extras field, renaming nodes, updating material hex colors, or changing texture paths.
  • Limitation: It is not recommended for structural operations that alter buffer lengths, accessors, or index arrays, as doing so requires manually recalculating byte offsets and lengths.

Choosing the Right Package

  • Choose @gltf-transform/core for full asset manipulation, structural edits, and robust handling of both geometry buffers and JSON relationships.
  • Choose gltf-pipeline for converting between glTF and GLB formats and managing file-embedding strategies.
  • Choose @loaders.gl/gltf for fast chunk-level parsing and repackaging.
  • Choose Native JSON parsing only for minor metadata edits on plain-text .gltf files.