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
.claude/rules/webgpu-renderer.mdWhat 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
WebGPURendererto 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
WebGPURendererfromthree/webgpuand initialize it before the first render. - Add
navigator.gpufeature detection and fall back to WebGL 2 when no adapter is available. - Show how to move particle updates into
instancedArraybuffers and compute shaders.
How to install webgpu-renderer
Manually: put the files in place
.claude/rules/webgpu-renderer.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/webgpu-renderer.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/webgpu-renderer.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/webgpu-renderer.mdManually: put the files in place
.clinerules/webgpu-renderer.mdStep 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