gltfjsx

Use the --types flag to generate a type-safe JSX component. This allows you to define a GLTFResult type that maps the nodes and materials from the GLTF file to specific Three.js types.

type GLTFResult = GLTF & {
  nodes: { robot: THREE.Mesh; rocket: THREE.Mesh }
  materials: { metal: THREE.MeshStandardMaterial; wood: THREE.MeshStandardMaterial }
}

export default function Model(props: JSX.IntrinsicElements['group']) {
  const { nodes, materials } = useGLTF<GLTFResult>('/model.gltf')

To use gltfjsx, ensure the following requirements are met:

• Node.js: Must be installed.
• GLTF File Location: The file must be present in your project's /public folder.
• three: version >= 122.x
• @react-three/fiber: version >= 5.x
• @react-three/drei: version >= 2.x

The --transform flag creates a binary-packed, draco-compressed, texture-resized, webp-compressed, deduped, instanced, and pruned .glb file ready for web consumption. This can reduce asset size by 70%-90%. It creates a copy of the original file with the suffix -transformed.glb.

Example command:

npx gltfjsx model.gltf --transform

You can use gltfjsx without a permanent installation by using npx. This tool converts GLTF assets into declarative and reusable react-three-fiber JSX components.

Basic usage:

npx gltfjsx [Model.glb] [options]

npx gltfjsx model.gltf --transform

The --instance flag identifies similar geometry and creates instances using drei/Merged. The --instanceall flag creates instances for every geometry to minimize draw calls.

To use instancing, you must import both the Instances wrapper and the Model component generated by the tool. Wrap your models in the Instances component to benefit from reduced draw calls.

Convert GLTF/GLB models into React components using the gltfjsx command-line tool. You can run it via npx.

Basic Usage:

$ npx gltfjsx [Model.glb] [options]

By default, the tool generates a .jsx file named after the model (capitalized). If the --types flag is used, it generates a .tsx file.

You can use the parse function directly in your code to convert a loaded GLTF object or a Three.js scene into JSX string content.

Parsing a GLTF object:

import { parse } from 'gltfjsx'
import { GLTFLoader, DRACOLoader } from 'three-stdlib'

const gltfLoader = new GLTFLoader()
const dracoloader = new DRACOLoader()
dracoloader.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/')
gltfLoader.setDRACOLoader(dracoloader)

gltfLoader.load(url, (gltf) => {
  const jsx = parse(gltf, optionalConfig)
})

Parsing a scene (Object3D):

const jsx = parse(scene, optionalConfig)

The GLTFStructureLoader allows you to extract the structure of a GLTF asset without loading actual binaries or textures. This is useful for running tests in environments where heavy assets are unavailable.

import { GLTFStructureLoader } from 'gltfjsx'
import fs from 'fs/promises'

const loader = new GLTFStructureLoader()
const data = await fs.readFile('./model.glb')
const { scene } = await new Promise((res) => loader.parse(data, '', res))