Skip to main content
rule CX Codex

webgpu-renderer — Claude Code rule: WebGPU setup and install

The webgpu-renderer rule guides Three.js WebGPU setup with a WebGL 2 fallback. Use it when a 3D scene needs compute work, GPU particles, or indirect rendering.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/webgpu-renderer.md
Open on GitHub

What webgpu-renderer does

The rule covers WebGPURenderer from three/webgpu, including the required await renderer.init() call before the first frame. It also shows when to use renderAsync for compute-heavy scenes and how to set forceWebGL: true while testing fallback behavior or shader differences.

Its examples include navigator.gpu feature checks, instancedArray buffers, storage textures, workgroup memory, and indirect draws. The guidance also covers moving physics to compute shaders, grouping frequently updated uniforms, and using Chrome WebGPU DevTools for debugging.

Browser support matters. Chrome and Edge need v113+, Firefox needs v141+ on Windows or v145+ on macOS ARM, and Safari needs v26+. Older Firefox versions require flags, so the fallback path should be tested in that environment.

What it helps with

  • connect WebGPURenderer to a Three.js scene
  • add asynchronous rendering for compute-heavy frames
  • detect WebGPU features before choosing a renderer
  • move particle updates to GPU compute
  • test the WebGL 2 fallback path

Example prompts for the agent

  • Set up WebGPURenderer from three/webgpu and initialize it before the first render.
  • Add navigator.gpu feature detection and fall back to WebGL 2 when no adapter is available.
  • Show how to move particle updates into instancedArray buffers and compute shaders.

How to install webgpu-renderer

Manually: put the files in place

.claude/rules/webgpu-renderer.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about webgpu-renderer

How do I install webgpu-renderer in Claude Code?

Place the rule at .claude/rules/webgpu-renderer.md in your project.

What does webgpu-renderer do?

It gives the agent guidance for Three.js WebGPU setup, async rendering, compute shaders, feature detection, and WebGL 2 fallback.

Which browsers support the webgpu-renderer setup?

Chrome and Edge require v113+, Firefox requires v141+ on Windows or v145+ on macOS ARM, and Safari requires v26+. Older Firefox versions need flags.

Source text

webgpu-renderer.md · MIT
# WebGPU Renderer

> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)

WebGPU is the next-generation graphics API. Three.js provides zero-config WebGPU with automatic WebGL 2 fallback.

## Setup

```javascript
import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer();
await renderer.init(); // Required before first render

function animate() {
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
animate();
```

## Browser Support Matrix

| Browser | Version | Notes |
|---------|---------|-------|
| Chrome/Edge | v113+ | Full support |
| Firefox | v141+ (Windows), v145+ (macOS ARM) | Requires flags in older versions |
| Safari | v26+ (September 2025) | WebKit support |

## Key Tips

### 1. Use `renderAsync` for Compute-Heavy Scenes

```javascript
async function animate() {
  await renderer.renderAsync(scene, camera);
  requestAnimationFrame(animate);
}
```

Ensures compute passes complete before dependent render passes.

### 2. Force WebGL for Testing

```javascript
const renderer = new WebGPURenderer({ forceWebGL: true });
```

Useful for testing fallback behavior and debugging shader differences.

### 3. Feature Detection

```javascript
const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) return; // Fallback to WebGL

const hasFloat32Filtering = adapter.features.has('float32-filterable');
const hasTimestamps = adapter.features.has('timestamp-query');
```

### 4. GPU-Persistent Buffers with `instancedArray`

```javascript
import { instancedArray } from 'three/tsl';

const positions = instancedArray(particleCount, 'vec3');
const velocities = instancedArray(particleCount, 'vec3');
```

CPU-based particle updates plateau around 50,000 particles; compute shaders enable millions.

### 5. Storage Textures for Read-Write Compute

```javascript
import { storageTexture, textureStore, uvec2 } from 'three/tsl';

const outputTexture = new StorageTexture(width, height);
const store = textureStore(outputTexture, uvec2(x, y), computedColor);
```

### 6. Workgroup Shared Memory

```javascript
import { workgroupArray, workgroupBarrier } from 'three/tsl';

const sharedData = workgroupArray('float', 256);
sharedData.element(localIndex).assign(inputData);
workgroupBarrier();
```

Shared memory operates 10-100x faster than global memory.

### 7. Indirect Draws for GPU-Driven Rendering

Let GPU determine what renders based on compute shader output, enabling frustum culling on GPU.

## When to Migrate to WebGPU

Prioritize migration when hitting performance walls in:
- Draw-call-heavy scenes
- Complex particle systems (>50k particles)
- Compute-intensive effects
- Complex shader pipelines

Expect 2-10x performance gains in these specific scenarios.

## Best Practices

1. **Minimize buffer updates per frame** - Batch multiple small updates into single operations
2. **Group frequently-updated uniforms** - WebGPU batches resources into bind groups; separate static from dynamic data
3. **Use compute shaders for physics** - Move CPU-bound physics to GPU compute
4. **Debug with Chrome WebGPU DevTools** - Enable "WebGPU Developer Features" in chrome://flags

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
shader-mobile The shader-mobile rule for Claude Code provides guidelines for optimizing GLSL and Three.js shaders for mobile GPUs to prevent framerate drops on mobile devices. CX Codex +1 ★ 4,719repo stars drei-use-gltf The drei-use-gltf rule guides GLTF loading through useGLTF, including caching and preloading. It fits React Three Fiber scenes that need model assets. CX Codex +1 ★ 4,719repo stars perf-zustand-selectors perf-zustand-selectors — a rule file that pushes the agent to subscribe components to individual Zustand slices instead of the whole store, so a component repaints only when the data it reads changes. CX Codex +1 ★ 4,719repo stars geometry-instanced-mesh geometry-instanced-mesh guides AI agents to use THREE.InstancedMesh instead of separate meshes for repeating 3D objects. CX Codex +1 ★ 4,719repo stars tsl-material-slots tsl-material-slots is a Claude Code rule with a reference to Three.js TSL material slots. It helps write node-based shader logic without mistyping slot names or property types. CX Codex +1 ★ 4,719repo stars core-web-vitals core-web-vitals is a Claude Code rule for loading Three.js models and textures without letting heavy 3D delay first paint or degrade LCP, FID and CLS. CX Codex +1 ★ 4,719repo stars postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars timeline-builder timeline-builder is a Claude Code skill that turns JSON event data into interactive HTML timelines with vertical, horizontal, or dual-side layouts. It covers project milestones, release histories, and resumes. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open