drei-use-gltf — Claude Code rule: what it does, how to install
The drei-use-gltf rule guides GLTF loading through useGLTF, including caching and preloading. It fits React Three Fiber scenes that need model assets.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/drei-use-gltf.mdWhat drei-use-gltf does
The rule directs the agent to use useGLTF from @react-three/drei for GLTF assets. The hook exposes the scene, nodes, and materials, works with React Suspense, reuses cached loads, and supports Draco decoding.
It shows how to call useGLTF.preload() at module scope, including for several model paths. Repeated objects should use scene.clone() so separate instances do not share state. The examples also cover typed GLTF results in TypeScript and dispose={null} when a model is shared.
The rule depends on @react-three/drei. A compressed asset also needs a Draco decoder path such as '/draco/'; R3F disposes objects automatically by default.
What it helps with
- load a GLTF asset with
useGLTF - start model loading before a component renders
- wrap model rendering in
Suspense - read meshes and materials from a GLTF result
- render separate copies of one scene
Example prompts for the agent
- Load
model.glbwithuseGLTFand render its scene in the component. - Add module-level preloading for
model1.glb,model2.glb, andmodel3.glb. - Render several
tree.glbinstances withscene.clone()and different positions.
How to install drei-use-gltf
Manually: put the files in place
.claude/rules/drei-use-gltf.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/drei-use-gltf.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/drei-use-gltf.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/drei-use-gltf.mdManually: put the files in place
.clinerules/drei-use-gltf.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about drei-use-gltf
How do I install drei-use-gltf in Claude Code?
Place the rule file at .claude/rules/drei-use-gltf.md.
What does drei-use-gltf do?
It tells the agent to load GLTF files with useGLTF from @react-three/drei. The guidance covers caching, Suspense, preloading, Draco support, node and material access, scene cloning, and disposal behavior.
How does drei-use-gltf handle Draco-compressed models?
Pass the decoder directory as the second argument: useGLTF('/model.glb', '/draco/'). Use the same decoder path when calling useGLTF.preload('/model.glb', '/draco/').
Source text
drei-use-gltf.md · MIT
# drei-use-gltf
**Use useGLTF for model loading with preloading.**
## Why It Matters
`useGLTF` from Drei provides:
- Suspense integration (automatic loading states)
- Caching (same model loaded once)
- Preloading capability
- Draco decompression support
## Basic Example
```jsx
import { useGLTF } from '@react-three/drei';
function Model() {
const { scene, nodes, materials } = useGLTF('/model.glb');
return <primitive object={scene} />;
}
```
## Preloading (Critical for UX)
```jsx
import { useGLTF } from '@react-three/drei';
function Model() {
const { scene } = useGLTF('/model.glb');
return <primitive object={scene} />;
}
// Preload at module level - starts loading immediately
useGLTF.preload('/model.glb');
// Or preload multiple models
useGLTF.preload(['/model1.glb', '/model2.glb', '/model3.glb']);
```
## With Draco Compression
```jsx
function DracoModel() {
// Second argument is the Draco decoder path
const { scene } = useGLTF('/model.glb', '/draco/');
return <primitive object={scene} />;
}
useGLTF.preload('/model.glb', '/draco/');
```
## Accessing Nodes and Materials
```jsx
function Character() {
const { nodes, materials } = useGLTF('/character.glb');
return (
<group>
<mesh
geometry={nodes.Body.geometry}
material={materials.Skin}
/>
<mesh
geometry={nodes.Clothes.geometry}
material={materials.Fabric}
/>
</group>
);
}
```
## Clone for Multiple Instances
```jsx
function Tree({ position }) {
const { scene } = useGLTF('/tree.glb');
// Clone to avoid sharing state between instances
return <primitive object={scene.clone()} position={position} />;
}
function Forest() {
return (
<>
<Tree position={[0, 0, 0]} />
<Tree position={[5, 0, 0]} />
<Tree position={[10, 0, 0]} />
</>
);
}
```
## With Suspense
```jsx
import { Suspense } from 'react';
import { useGLTF } from '@react-three/drei';
function Model() {
const { scene } = useGLTF('/model.glb');
return <primitive object={scene} />;
}
function Scene() {
return (
<Suspense fallback={<LoadingBox />}>
<Model />
</Suspense>
);
}
function LoadingBox() {
return (
<mesh>
<boxGeometry />
<meshBasicMaterial wireframe color="white" />
</mesh>
);
}
```
## TypeScript Types
```tsx
import { useGLTF } from '@react-three/drei';
import { GLTF } from 'three-stdlib';
type GLTFResult = GLTF & {
nodes: {
Body: THREE.Mesh;
Head: THREE.Mesh;
};
materials: {
Skin: THREE.MeshStandardMaterial;
};
};
function Model() {
const { nodes, materials } = useGLTF('/model.glb') as GLTFResult;
// Now nodes.Body and materials.Skin are typed
}
```
## Dispose Handling
R3F auto-disposes by default. To prevent disposal (for shared models):
```jsx
function SharedModel({ model }) {
return <primitive object={model} dispose={null} />;
}
```
## References
- [Drei useGLTF](https://github.com/pmndrs/drei#usegltf)
- [gltfjsx](https://github.com/pmndrs/gltfjsx) - Generate JSX from GLTF
© zebbern · MIT · zebbern/claude-code-guide