Shader Lab
Set up @basementstudio/shader-lab — a React runtime that plays compositions authored in the Shader Lab editor. Compositions can stack text layers, image layers, and custom TSL (Three Shading Language) shader layers, with a timeline, and can be used as a DOM element, as a texture in a three.js scene, or as a post-processing pass.
Full suite, not just text. The same runtime renders any composition the editor can export.
When to use
- User wants a bespoke shader-driven hero, background, or accent on a landing page.
- User wants to reuse compositions they already built (or will build) in the Shader Lab editor at https://eng.basement.studio/tools/shader-lab.
- User wants post-processing (bloom, grain, distortion) over an existing three.js / R3F scene.
Before installing, confirm browser scope
This runtime requires WebGPU. That means:
- Chrome, Edge: supported
- Safari 18+: supported
- Firefox: behind a flag as of early 2026
Ask the user if a WebGPU-only effect is acceptable for their audience. If not, either:
- Build a CSS / canvas2D fallback for non-WebGPU browsers and gate the shader behind a capability check, or
- Use a different tool (react-three-fiber + fragment shader on a mesh is a WebGL alternative with broader reach).
Do not skip this check — shipping a silently-broken hero on Firefox is worse than not shipping it.
Steps
Check if already installed
- Look for
@basementstudio/shader-lab in package.json dependencies.
- If found, skip install and move to step 4.
Detect package manager
bun.lock or bun.lockb → bun
pnpm-lock.yaml → pnpm
yarn.lock → yarn
- else → npm
Install the runtime and three.js
bun add @basementstudio/shader-lab three
bun add -d @types/three
(substitute npm install / pnpm add / yarn add per manager)
Create a compositions directory
Recommended path: src/shaders/compositions/ (or app/_shaders/compositions/ in pure App Router projects).
Each composition lives in its own file as a typed config. Structure:
src/shaders/
├── compositions/
│ ├── hero.ts
│ ├── accent-warp.ts
│ └── background-flow.ts
└── ShaderComposition.tsx // thin client wrapper around ShaderLabComposition
Add the client wrapper
ShaderLabComposition and the hooks are client-side only. In Next.js App Router, wrap them in a "use client" component so server components can import it freely.
src/shaders/ShaderComposition.tsx:
"use client";
import { ShaderLabComposition } from "@basementstudio/shader-lab";
import type { ComponentProps } from "react";
type Config = ComponentProps<typeof ShaderLabComposition>["config"];
export function ShaderComposition({
config,
onRuntimeError,
}: {
config: Config;
onRuntimeError?: (message: string) => void;
}) {
return (
<ShaderLabComposition
config={config}
onRuntimeError ??
((message) => {
if (process.env.NODE_ENV !== "production") {
console.error("[shader-lab]", message);
}
})
}
/>
);
}
Add a WebGPU capability guard
src/shaders/useSupportsWebGPU.ts:
"use client";
import { useEffect, useState } from "react";
export function useSupportsWebGPU(): boolean | null {
const [supported, setSupported] = useState<boolean | null>(null);
useEffect(() => {
const gpu = (navigator as Navigator & { gpu?: unknown }).gpu;
setSupported(Boolean(gpu));
}, []);
return supported;
}
Usage on a page:
"use client";
import { ShaderComposition } from "@/shaders/ShaderComposition";
import { useSupportsWebGPU } from "@/shaders/useSupportsWebGPU";
import { heroConfig } from "@/shaders/compositions/hero";
import { HeroFallback } from "@/components/HeroFallback";
export function Hero() {
const supported = useSupportsWebGPU();
if (supported === null) return null; // avoid flash during detection
if (!supported) return <HeroFallback />;
return <ShaderComposition config={heroConfig} />;
}
Author compositions
The primary way to build a composition is in the Shader Lab editor at https://eng.basement.studio/tools/shader-lab. Export gives you a config object you can paste into a file under src/shaders/compositions/.
Minimal handwritten example for reference:
import type { ComponentProps } from "react";
import type { ShaderLabComposition } from "@basementstudio/shader-lab";
type Config = ComponentProps<typeof ShaderLabComposition>["config"];
export const heroConfig: Config = {
layers: [
{ type: "text", content: "Your text" },
// stack a custom shader layer above for effects:
// { type: "customShader", sketch: yourSketchFn },
],
timeline: { duration: 6, loop: true, tracks: [] },
};
Custom shader layers use TSL (Three Shading Language) — a Fn()-wrapped function that returns a TSL node. Injected globals include time, inputTexture, and noise / tonemapping / SDF helpers. Write these in the editor first, then export.
Advanced: compositions as textures or post-processing
- Composition as a texture in an R3F scene: use
useShaderLab(config, { width, height, pixelRatio }) and pass the returned texture to a material.
- Post-processing over an existing renderer:
useShaderLab(config, { renderer }) and drive it with postprocessing.render(inputTexture, time, delta) in your render loop.
- Manual render loop:
useShaderLabCanvasSource / useShaderLabPostProcessingSource for full control.
These are client-side, same "use client" rule applies.
Where configs live
Treat composition configs as content, not code. They belong in a dedicated directory (src/shaders/compositions/) next to any per-composition sketch functions. Reuse configs across projects by copy or by referencing a shared package if the studio maintains one.
Troubleshooting
- Blank output, no error: likely WebGPU not available. Add the capability guard above.
- "Runtime error" callback fires: inspect the message, most common cause is an invalid sketch function or an unsupported TSL node. Reopen the composition in the Shader Lab editor and re-export.
- SSR hydration warning: the component is client-only. Ensure the parent is marked
"use client" or imported via dynamic(() => ..., { ssr: false }).
- Three.js version conflict:
three is a peer dep. If another package pins an incompatible version, resolve with overrides / resolutions in package.json.
References
1---2name: shader-lab3description: Install and use Basement Studio's Shader Lab runtime to drop GPU shader compositions into a Next.js or React app. Use when the user wants shader-driven visual effects — warped text, liquid backgrounds, distortion, noise flows, post-processing passes, animated hero treatments — sourced from the Shader Lab editor. Triggers include shader, shaders, shader-lab, basement shader, shader effects, gpu effects, shader composition, warped text, liquid background, displacement text, hero shader, shader post-processing.4author: Basement Studio (https://github.com/basementstudio/shader-lab)5metadata:6 source: https://skillmd.com/skills/tommylower/shader-lab7---89# Shader Lab1011Set up `@basementstudio/shader-lab` — a React runtime that plays compositions authored in the Shader Lab editor. Compositions can stack text layers, image layers, and custom TSL (Three Shading Language) shader layers, with a timeline, and can be used as a DOM element, as a texture in a three.js scene, or as a post-processing pass.1213Full suite, not just text. The same runtime renders any composition the editor can export.1415## When to use1617- User wants a bespoke shader-driven hero, background, or accent on a landing page.18- User wants to reuse compositions they already built (or will build) in the Shader Lab editor at https://eng.basement.studio/tools/shader-lab.19- User wants post-processing (bloom, grain, distortion) over an existing three.js / R3F scene.2021## Before installing, confirm browser scope2223This runtime requires **WebGPU**. That means:2425- Chrome, Edge: supported26- Safari 18+: supported27- Firefox: behind a flag as of early 20262829Ask the user if a WebGPU-only effect is acceptable for their audience. If not, either:3031- Build a CSS / canvas2D fallback for non-WebGPU browsers and gate the shader behind a capability check, or32- Use a different tool (react-three-fiber + fragment shader on a mesh is a WebGL alternative with broader reach).3334Do not skip this check — shipping a silently-broken hero on Firefox is worse than not shipping it.3536## Steps37381. **Check if already installed**39 - Look for `@basementstudio/shader-lab` in `package.json` dependencies.40 - If found, skip install and move to step 4.41422. **Detect package manager**43 - `bun.lock` or `bun.lockb` → bun44 - `pnpm-lock.yaml` → pnpm45 - `yarn.lock` → yarn46 - else → npm47483. **Install the runtime and three.js**49 ```bash50 bun add @basementstudio/shader-lab three51 bun add -d @types/three52 ```53 (substitute `npm install` / `pnpm add` / `yarn add` per manager)54554. **Create a compositions directory**5657 Recommended path: `src/shaders/compositions/` (or `app/_shaders/compositions/` in pure App Router projects).5859 Each composition lives in its own file as a typed config. Structure:60 ```61 src/shaders/62 ├── compositions/63 │ ├── hero.ts64 │ ├── accent-warp.ts65 │ └── background-flow.ts66 └── ShaderComposition.tsx // thin client wrapper around ShaderLabComposition67 ```68695. **Add the client wrapper**7071 `ShaderLabComposition` and the hooks are client-side only. In Next.js App Router, wrap them in a `"use client"` component so server components can import it freely.7273 `src/shaders/ShaderComposition.tsx`:74 ```tsx75 "use client";7677 import { ShaderLabComposition } from "@basementstudio/shader-lab";78 import type { ComponentProps } from "react";7980 type Config = ComponentProps<typeof ShaderLabComposition>["config"];8182 export function ShaderComposition({83 config,84 onRuntimeError,85 }: {86 config: Config;87 onRuntimeError?: (message: string) => void;88 }) {89 return (90 <ShaderLabComposition91 config={config}92 onRuntimeError={93 onRuntimeError ??94 ((message) => {95 if (process.env.NODE_ENV !== "production") {96 console.error("[shader-lab]", message);97 }98 })99 }100 />101 );102 }103 ```1041056. **Add a WebGPU capability guard**106107 `src/shaders/useSupportsWebGPU.ts`:108 ```tsx109 "use client";110111 import { useEffect, useState } from "react";112113 export function useSupportsWebGPU(): boolean | null {114 const [supported, setSupported] = useState<boolean | null>(null);115116 useEffect(() => {117 const gpu = (navigator as Navigator & { gpu?: unknown }).gpu;118 setSupported(Boolean(gpu));119 }, []);120121 return supported;122 }123 ```124125 Usage on a page:126 ```tsx127 "use client";128129 import { ShaderComposition } from "@/shaders/ShaderComposition";130 import { useSupportsWebGPU } from "@/shaders/useSupportsWebGPU";131 import { heroConfig } from "@/shaders/compositions/hero";132 import { HeroFallback } from "@/components/HeroFallback";133134 export function Hero() {135 const supported = useSupportsWebGPU();136 if (supported === null) return null; // avoid flash during detection137 if (!supported) return <HeroFallback />;138 return <ShaderComposition config={heroConfig} />;139 }140 ```1411427. **Author compositions**143144 The primary way to build a composition is in the **Shader Lab editor** at https://eng.basement.studio/tools/shader-lab. Export gives you a config object you can paste into a file under `src/shaders/compositions/`.145146 Minimal handwritten example for reference:147 ```ts148 import type { ComponentProps } from "react";149 import type { ShaderLabComposition } from "@basementstudio/shader-lab";150151 type Config = ComponentProps<typeof ShaderLabComposition>["config"];152153 export const heroConfig: Config = {154 layers: [155 { type: "text", content: "Your text" },156 // stack a custom shader layer above for effects:157 // { type: "customShader", sketch: yourSketchFn },158 ],159 timeline: { duration: 6, loop: true, tracks: [] },160 };161 ```162163 Custom shader layers use TSL (Three Shading Language) — a `Fn()`-wrapped function that returns a TSL node. Injected globals include `time`, `inputTexture`, and noise / tonemapping / SDF helpers. Write these in the editor first, then export.1641658. **Advanced: compositions as textures or post-processing**166167 - **Composition as a texture in an R3F scene**: use `useShaderLab(config, { width, height, pixelRatio })` and pass the returned `texture` to a material.168 - **Post-processing over an existing renderer**: `useShaderLab(config, { renderer })` and drive it with `postprocessing.render(inputTexture, time, delta)` in your render loop.169 - **Manual render loop**: `useShaderLabCanvasSource` / `useShaderLabPostProcessingSource` for full control.170171 These are client-side, same `"use client"` rule applies.172173## Where configs live174175Treat composition configs as content, not code. They belong in a dedicated directory (`src/shaders/compositions/`) next to any per-composition sketch functions. Reuse configs across projects by copy or by referencing a shared package if the studio maintains one.176177## Troubleshooting178179- **Blank output, no error**: likely WebGPU not available. Add the capability guard above.180- **"Runtime error" callback fires**: inspect the message, most common cause is an invalid sketch function or an unsupported TSL node. Reopen the composition in the Shader Lab editor and re-export.181- **SSR hydration warning**: the component is client-only. Ensure the parent is marked `"use client"` or imported via `dynamic(() => ..., { ssr: false })`.182- **Three.js version conflict**: `three` is a peer dep. If another package pins an incompatible version, resolve with `overrides` / `resolutions` in `package.json`.183184## References185186- Runtime README: https://github.com/basementstudio/shader-lab187- Editor: https://eng.basement.studio/tools/shader-lab188- TSL docs: https://threejs.org/docs/?q=tsl (Three Shading Language)