vite-plugin-gltf

4.0.0 verified Mon Apr 27 auth: no javascript

Vite plugin for optimizing glTF 3D models during build. Version 4.0.0 is the latest stable release. Released by The New York Times R&D, it relies on the glTF Transform ecosystem for transforms like texture resizing, Draco compression, and mesh quantization. Unlike other glTF tooling that requires separate CLI steps, this integrates seamlessly into Vite's build pipeline. It is ESM-only, requires Node 18+, and all peer dependencies must be installed manually.

Common errors

error Error: Cannot find module '@gltf-transform/core' ↓

cause Missing peer dependency @gltf-transform/core.

fix

Install it: npm install @gltf-transform/core

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() for an ESM-only plugin.

fix

Change to import statement or use dynamic import(). Ensure project is ESM (type: module in package.json).

error TypeError: gltf is not a function ↓

cause Using the plugin incorrectly (e.g., gltf as a default export outside Vite config).

fix

Use it inside Vite's plugins array: export default defineConfig({ plugins: [gltf({...})] })

error error: unknown option '--format es' ↓

cause Using outdated Vite version that doesn't support modern Vite 5 flags.

fix

Update Vite to version 5+.

Warnings

breaking Requires Node.js 18 or later due to ESM-only builds and modern APIs. ↓

fix Upgrade Node.js to version 18 or higher.

breaking Peer dependencies must be installed manually; optional dependencies are not included. ↓

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

gotcha When using TypeScript, ensure 'skipLibCheck' is true or resolve types for @gltf-transform/* packages. ↓

fix Add to tsconfig.json: { "compilerOptions": { "skipLibCheck": true } }

deprecated Transform options using 'encoder' and 'decoder' for Draco are deprecated; use 'draco()' from @gltf-transform/functions. ↓

fix Replace encoder/decoder options with the draco() transform function.

gotcha Vite 5+ required; older Vite versions may cause plugin incompatibility. ↓

fix Update Vite to version 5 or later.

Install

npm install vite-plugin-gltf

yarn add vite-plugin-gltf

pnpm add vite-plugin-gltf

Imports

default

wrong

const gltf = require('vite-plugin-gltf')

correct

import gltf from 'vite-plugin-gltf'

ESM-only since v3; CommonJS require will fail.

gltf (type)

wrong

import { PluginOptions } from 'vite-plugin-gltf'

correct

import type { PluginOptions } from 'vite-plugin-gltf'

TypeScript users: use 'import type' for type-only imports to avoid runtime errors.

defineConfig

wrong

import gltf from 'vite-plugin-gltf'
export default gltf()

correct

import { defineConfig } from 'vite'
import gltf from 'vite-plugin-gltf'

Plugin must be used inside defineConfig or an array of plugins, not as the default export.

Quickstart

Configures vite-plugin-gltf with texture resizing and Draco compression transforms.

// vite.config.js
import { defineConfig } from 'vite';
import gltf from 'vite-plugin-gltf';
import { textureResize, draco } from '@gltf-transform/functions';

export default defineConfig({
  plugins: [
    gltf({
      transforms: [
        textureResize({ size: [1024, 1024] }),
        draco()
      ]
    })
  ]
});