tsl-why-use — Claude Code rule: TSL instead of onBeforeCompile
tsl-why-use — a rule that pushes the coding agent to build custom Three.js materials from TSL nodes rather than patching shaders through onBeforeCompile.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/tsl-why-use.mdWhat tsl-why-use does
Custom Three.js materials are the target. The rule steers the agent away from onBeforeCompile, where you splice uniforms and shader chunks into fragmentShader by string replacement, and toward node materials built from three/tsl.
What shows up in practice: colour animation from sin(time) on colorNode, vertex displacement through positionNode, repeated formulas wrapped in Fn. Nodes compose, so a second texture just multiplies into the colour node you already have instead of hunting for the right #include token.
The examples import from three/tsl and construct MeshStandardNodeMaterial, so code written under this rule needs a Three.js build that ships node materials. On an older version it will not run. String-level shader patches break when Three.js updates, which is the reason to keep the rule in the repo.
What it helps with
- replace an
onBeforeCompileshader patch with a TSL node material - layer a detail texture onto a standard material without editing
fragmentShader - animate a material colour from time with a sine
- displace vertices along a sine wave in
positionNode - wrap a repeated formula in
Fnand reuse it
Example prompts for the agent
- Rewrite this
fragmentShaderpatch with nodes fromthree/tsl. - Add a detail texture to the material in TSL, keep
onBeforeCompileout of it. - Animate the material colour with a sine of time on
colorNode.
How to install tsl-why-use
Manually: put the files in place
.claude/rules/tsl-why-use.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/tsl-why-use.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/tsl-why-use.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/tsl-why-use.mdManually: put the files in place
.clinerules/tsl-why-use.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about tsl-why-use
How do I install tsl-why-use in Claude Code?
Create the rule file at .claude/rules/tsl-why-use.md. The rule text comes from the zebbern/claude-code-guide repository.
What does tsl-why-use do?
It tells the agent to assemble custom Three.js materials from three/tsl nodes and MeshStandardNodeMaterial instead of replacing strings inside onBeforeCompile.
Why prefer TSL over onBeforeCompile?
TSL nodes run on WebGL and WebGPU, are typed, and combine with each other. String-replacement patches in fragmentShader break when Three.js updates and clash with other edits.
Source text
tsl-why-use.md · MIT
# tsl-why-use
**Use TSL instead of onBeforeCompile hacks for custom materials.**
## Why It Matters
TSL (Three.js Shading Language) is the modern approach to shader creation in Three.js:
- Works with both WebGL and WebGPU backends
- No string manipulation or onBeforeCompile hacks
- Type-safe, composable shader nodes
- Automatic optimization and tree shaking
- Easier to maintain and debug
## Bad Example
```javascript
// OLD - onBeforeCompile (fragile, hard to maintain)
const material = new THREE.MeshStandardMaterial();
material.map = colorMap;
material.onBeforeCompile = (shader) => {
shader.uniforms.detailMap = { value: detailMap };
let token = '#define STANDARD';
let insert = `uniform sampler2D detailMap;`;
shader.fragmentShader = shader.fragmentShader.replace(token, token + insert);
token = '#include <map_fragment>';
insert = `diffuseColor *= texture2D(detailMap, vMapUv * 10.0);`;
shader.fragmentShader = shader.fragmentShader.replace(token, token + insert);
};
```
Problems:
- String manipulation is error-prone
- Breaks with Three.js updates
- Hard to combine multiple modifications
- No type safety
- Difficult to debug
## Good Example
```javascript
// NEW - TSL (clean, composable)
import { texture, uv } from 'three/tsl';
const detail = texture(detailMap, uv().mul(10));
const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture(colorMap).mul(detail);
```
Benefits:
- Clean, readable code
- Composable nodes
- Works with WebGL and WebGPU
- Type-safe with TypeScript
- Automatic optimization
## More TSL Examples
### Animated Color
```javascript
import { color, time, sin } from 'three/tsl';
const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0x00ff00).mul(sin(time).mul(0.5).add(0.5));
```
### Vertex Displacement
```javascript
import { positionLocal, sin, time } from 'three/tsl';
const material = new THREE.MeshStandardNodeMaterial();
material.positionNode = positionLocal.add(
sin(time.add(positionLocal.y)).mul(0.1)
);
```
### Custom Function
```javascript
import { Fn, vec3, float } from 'three/tsl';
const oscSine = Fn(([t = time]) => {
return t.add(0.75).mul(Math.PI * 2).sin().mul(0.5).add(0.5);
});
material.colorNode = vec3(oscSine(), 0, 0);
```
## References
- [Three.js TSL Documentation](https://threejs.org/docs/#api/en/nodes/TSL)
- [TSL Examples](https://threejs.org/examples/?q=tsl)
© zebbern · MIT · zebbern/claude-code-guide