rollup-plugin-gltf

4.0.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin for optimizing glTF 3D models during the bundling process, version 4.0.0. It integrates with the @gltf-transform ecosystem (core, extensions, functions) to apply transforms such as texture resizing, mesh deduplication, and quantization. Unlike manual CLI tools, it runs as part of a Rollup build, enabling per-file transforms and caching. The plugin is maintained by The New York Times R&D team and is released as-is. Compatible with Rollup 3+ and requires peer dependencies @gltf-transform/core, @gltf-transform/extensions, and @gltf-transform/functions at version 3.x.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'rollup-plugin-gltf' ↓

cause Using require() in a CommonJS file; package is ESM-only.

fix

Switch to import syntax or use dynamic import: const gltf = (await import('rollup-plugin-gltf')).default;

error TypeError: gltf is not a function ↓

cause Importing default incorrectly or using CJS require which returns an empty object.

fix

Use 'import gltf from 'rollup-plugin-gltf'' and ensure your project is configured for ESM.

error Cannot find module '@gltf-transform/core' or '@gltf-transform/functions' ↓

cause Missing peer dependencies; required at runtime.

fix

Run: npm install --save-dev @gltf-transform/core @gltf-transform/extensions @gltf-transform/functions

Warnings

breaking Peer dependency @gltf-transform/core must be version 3.x; installing version 2.x will cause type errors. ↓

fix Ensure package.json includes '@gltf-transform/core': '^3.0.0'

breaking ESM-only: require() will throw ERR_MODULE_NOT_FOUND or similar. ↓

fix Use import syntax or dynamic import() in CJS projects. Convert project to ESM if possible.

gotcha The 'transforms' option must be an array; passing a single function or missing property will cause transform to be silently skipped. ↓

fix Always provide transforms as an array, e.g., gltf({ transforms: [myTransform] })

deprecated The 'compress' option was removed in v4, use transforms with @gltf-transform/functions instead. ↓

fix Replace compress: true with transforms: [/* appropriate functions */]

Install

npm install rollup-plugin-gltf

yarn add rollup-plugin-gltf

pnpm add rollup-plugin-gltf

Imports

default (gltf)
wrong
```
const gltf = require('rollup-plugin-gltf');
```
correct
```
import gltf from 'rollup-plugin-gltf';
```
Package is ESM-only; CommonJS require will fail (module not found). Use dynamic import if needed.
gltf function type (TypeScript)
```
import type { GltfOptions } from 'rollup-plugin-gltf';
```
TypeScript users can import the options type for better autocompletion. Not available in CJS.
Plugin instance
wrong
```
new gltf({ transforms: [] })
```
correct
```
gltf({ transforms: [textureResize({size: [1024, 1024]})] })
```
The gltf function returns a plugin object; do not use 'new'. Options object required, even if empty.

Quickstart

Rollup configuration that optimizes glTF files by resizing textures to 1024x1024 and deduplicating meshes during build.

// rollup.config.js
import gltf from 'rollup-plugin-gltf';
import { textureResize } from '@gltf-transform/functions';
import { dedup } from '@gltf-transform/functions';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    gltf({
      transforms: [
        textureResize({ size: [1024, 1024] }),
        dedup()
      ]
    })
  ]
};