1# WebGPU & Three.js for Expo
2 
3**Use this skill for ANY 3D graphics, games, GPU compute, or Three.js features in React Native.**
4 
5## Locked Versions (Tested & Working)
6 
7```json
8{
9  "react-native-wgpu": "^0.4.1",
10  "three": "0.172.0",
11  "@react-three/fiber": "^9.4.0",
12  "wgpu-matrix": "^3.0.2",
13  "@types/three": "0.172.0"
14}
15```
16 
17**Critical:** These versions are tested together. Mismatched versions cause type errors and runtime issues.
18 
19## Installation
20 
21```bash
22npm install react-native-wgpu@^0.4.1 [email protected] @react-three/fiber@^9.4.0 wgpu-matrix@^3.0.2 @types/[email protected] --legacy-peer-deps
23```
24 
25**Note:** `--legacy-peer-deps` may be required due to peer dependency conflicts with canary Expo versions.
26 
27## Metro Configuration
28 
29Create `metro.config.js` in project root:
30 
31```js
32const { getDefaultConfig } = require("expo/metro-config");
33 
34const config = getDefaultConfig(__dirname);
35 
36config.resolver.resolveRequest = (context, moduleName, platform) => {
37  // Force 'three' to webgpu build
38  if (moduleName.startsWith("three")) {
39    moduleName = "three/webgpu";
40  }
41 
42  // Use standard react-three/fiber instead of React Native version
43  if (platform !== "web" && moduleName.startsWith("@react-three/fiber")) {
44    return context.resolveRequest(
45      {
46        ...context,
47        unstable_conditionNames: ["module"],
48        mainFields: ["module"],
49      },
50      moduleName,
51      platform
52    );
53  }
54  return context.resolveRequest(context, moduleName, platform);
55};
56 
57module.exports = config;
58```
59 
60## Required Lib Files
61 
62Create these files in `src/lib/`:
63 
64### 1. make-webgpu-renderer.ts
65 
66```ts
67import type { NativeCanvas } from "react-native-wgpu";
68import * as THREE from "three/webgpu";
69 
70export class ReactNativeCanvas {
71  constructor(private canvas: NativeCanvas) {}
72 
73  get width() {
74    return this.canvas.width;
75  }
76  get height() {
77    return this.canvas.height;
78  }
79  set width(width: number) {
80    this.canvas.width = width;
81  }
82  set height(height: number) {
83    this.canvas.height = height;
84  }
85  get clientWidth() {
86    return this.canvas.width;
87  }
88  get clientHeight() {
89    return this.canvas.height;
90  }
91  set clientWidth(width: number) {
92    this.canvas.width = width;
93  }
94  set clientHeight(height: number) {
95    this.canvas.height = height;
96  }
97 
98  addEventListener(_type: string, _listener: EventListener) {}
99  removeEventListener(_type: string, _listener: EventListener) {}
100  dispatchEvent(_event: Event) {}
101  setPointerCapture() {}
102  releasePointerCapture() {}
103}
104 
105export const makeWebGPURenderer = (
106  context: GPUCanvasContext,
107  { antialias = true }: { antialias?: boolean } = {}
108) =>
109  new THREE.WebGPURenderer({
110    antialias,
111    // @ts-expect-error
112    canvas: new ReactNativeCanvas(context.canvas),
113    context,
114  });
115```
116 
117### 2. fiber-canvas.tsx
118 
119```tsx
120import * as THREE from "three/webgpu";
121import React, { useEffect, useRef } from "react";
122import type { ReconcilerRoot, RootState } from "@react-three/fiber";
123import {
124  extend,
125  createRoot,
126  unmountComponentAtNode,
127  events,
128} from "@react-three/fiber";
129import type { ViewProps } from "react-native";
130import { PixelRatio } from "react-native";
131import { Canvas, type CanvasRef } from "react-native-wgpu";
132 
133import {
134  makeWebGPURenderer,
135  ReactNativeCanvas,
136} from "@/lib/make-webgpu-renderer";
137 
138// Extend THREE namespace for R3F - add all components you use
139extend({
140  AmbientLight: THREE.AmbientLight,
141  DirectionalLight: THREE.DirectionalLight,
142  PointLight: THREE.PointLight,
143  SpotLight: THREE.SpotLight,
144  Mesh: THREE.Mesh,
145  Group: THREE.Group,
146  Points: THREE.Points,
147  BoxGeometry: THREE.BoxGeometry,
148  SphereGeometry: THREE.SphereGeometry,
149  CylinderGeometry: THREE.CylinderGeometry,
150  ConeGeometry: THREE.ConeGeometry,
151  DodecahedronGeometry: THREE.DodecahedronGeometry,
152  BufferGeometry: THREE.BufferGeometry,
153  BufferAttribute: THREE.BufferAttribute,
154  MeshStandardMaterial: THREE.MeshStandardMaterial,
155  MeshBasicMaterial: THREE.MeshBasicMaterial,
156  PointsMaterial: THREE.PointsMaterial,
157  PerspectiveCamera: THREE.PerspectiveCamera,
158  Scene: THREE.Scene,
159});
160 
161interface FiberCanvasProps {
162  children: React.ReactNode;
163  style?: ViewProps["style"];
164  camera?: THREE.PerspectiveCamera;
165  scene?: THREE.Scene;
166}
167 
168export const FiberCanvas = ({
169  children,
170  style,
171  scene,
172  camera,
173}: FiberCanvasProps) => {
174  const root = useRef<ReconcilerRoot<OffscreenCanvas>>(null!);
175  const canvasRef = useRef<CanvasRef>(null);
176 
177  useEffect(() => {
178    const context = canvasRef.current!.getContext("webgpu")!;
179    const renderer = makeWebGPURenderer(context);
180 
181    // @ts-expect-error - ReactNativeCanvas wraps native canvas
182    const canvas = new ReactNativeCanvas(context.canvas) as HTMLCanvasElement;
183    canvas.width = canvas.clientWidth * PixelRatio.get();
184    canvas.height = canvas.clientHeight * PixelRatio.get();
185    const size = {
186      top: 0,
187      left: 0,
188      width: canvas.clientWidth,
189      height: canvas.clientHeight,
190    };
191 
192    if (!root.current) {
193      root.current = createRoot(canvas);
194    }
195    root.current.configure({
196      size,
197      events,
198      scene,
199      camera,
200      gl: renderer,
201      frameloop: "always",
202      dpr: 1,
203      onCreated: async (state: RootState) => {
204        // @ts-expect-error - WebGPU renderer has init method
205        await state.gl.init();
206        const renderFrame = state.gl.render.bind(state.gl);
207        state.gl.render = (s: THREE.Scene, c: THREE.Camera) => {
208          renderFrame(s, c);
209          context?.present();
210        };
211      },
212    });
213    root.current.render(children);
214    return () => {
215      if (canvas != null) {
216        unmountComponentAtNode(canvas!);
217      }
218    };
219  });
220 
221  return <Canvas ref={canvasRef} style={style} />;
222};
223```
224 
225## Basic 3D Scene
226 
227```tsx
228import * as THREE from "three/webgpu";
229import { View } from "react-native";
230import { useRef } from "react";
231import { useFrame, useThree } from "@react-three/fiber";
232import { FiberCanvas } from "@/lib/fiber-canvas";
233 
234function RotatingBox() {
235  const ref = useRef<THREE.Mesh>(null!);
236 
237  useFrame((_, delta) => {
238    ref.current.rotation.x += delta;
239    ref.current.rotation.y += delta * 0.5;
240  });
241 
242  return (
243    <mesh ref={ref}>
244      <boxGeometry args={[1, 1, 1]} />
245      <meshStandardMaterial color="hotpink" />
246    </mesh>
247  );
248}
249 
250function Scene() {
251  const { camera } = useThree();
252 
253  useEffect(() => {
254    camera.position.set(0, 2, 5);
255    camera.lookAt(0, 0, 0);
256  }, [camera]);
257 
258  return (
259    <>
260      <ambientLight intensity={0.5} />
261      <directionalLight position={[10, 10, 5]} intensity={1} />
262      <RotatingBox />
263    </>
264  );
265}
266 
267export default function App() {
268  return (
269    <View style={{ flex: 1 }}>
270      <FiberCanvas style={{ flex: 1 }}>
271        <Scene />
272      </FiberCanvas>
273    </View>
274  );
275}
276```
277 
278## Lazy Loading (Recommended)
279 
280Use React.lazy to code-split Three.js for better loading:
281 
282```tsx
283import React, { Suspense } from "react";
284import { ActivityIndicator, View } from "react-native";
285 
286const Scene = React.lazy(() => import("@/components/scene"));
287 
288export default function Page() {
289  return (
290    <View style={{ flex: 1 }}>
291      <Suspense fallback={<ActivityIndicator size="large" />}>
292        <Scene />
293      </Suspense>
294    </View>
295  );
296}
297```
298 
299## Common Geometries
300 
301```tsx
302// Box
303<mesh>
304  <boxGeometry args={[width, height, depth]} />
305  <meshStandardMaterial color="red" />
306</mesh>
307 
308// Sphere
309<mesh>
310  <sphereGeometry args={[radius, widthSegments, heightSegments]} />
311  <meshStandardMaterial color="blue" />
312</mesh>
313 
314// Cylinder
315<mesh>
316  <cylinderGeometry args={[radiusTop, radiusBottom, height, segments]} />
317  <meshStandardMaterial color="green" />
318</mesh>
319 
320// Cone
321<mesh>
322  <coneGeometry args={[radius, height, segments]} />
323  <meshStandardMaterial color="yellow" />
324</mesh>
325```
326 
327## Lighting
328 
329```tsx
330// Ambient (uniform light everywhere)
331<ambientLight intensity={0.5} />
332 
333// Directional (sun-like)
334<directionalLight position={[10, 10, 5]} intensity={1} />
335 
336// Point (light bulb)
337<pointLight position={[0, 5, 0]} intensity={2} distance={10} />
338 
339// Spot (flashlight)
340<spotLight position={[0, 10, 0]} angle={0.3} penumbra={1} intensity={2} />
341```
342 
343## Animation with useFrame
344 
345```tsx
346import { useFrame } from "@react-three/fiber";
347import { useRef } from "react";
348import * as THREE from "three/webgpu";
349 
350function AnimatedMesh() {
351  const ref = useRef<THREE.Mesh>(null!);
352 
353  // Runs every frame - delta is time since last frame
354  useFrame((state, delta) => {
355    // Rotate
356    ref.current.rotation.y += delta;
357 
358    // Oscillate position
359    ref.current.position.y = Math.sin(state.clock.elapsedTime) * 2;
360  });
361 
362  return (
363    <mesh ref={ref}>
364      <boxGeometry />
365      <meshStandardMaterial color="orange" />
366    </mesh>
367  );
368}
369```
370 
371## Particle Systems
372 
373```tsx
374import * as THREE from "three/webgpu";
375import { useRef, useEffect } from "react";
376import { useFrame } from "@react-three/fiber";
377 
378function Particles({ count = 500 }) {
379  const ref = useRef<THREE.Points>(null!);
380  const positions = useRef<Float32Array>(new Float32Array(count * 3));
381 
382  useEffect(() => {
383    for (let i = 0; i < count; i++) {
384      positions.current[i * 3] = (Math.random() - 0.5) * 50;
385      positions.current[i * 3 + 1] = (Math.random() - 0.5) * 50;
386      positions.current[i * 3 + 2] = (Math.random() - 0.5) * 50;
387    }
388  }, [count]);
389 
390  useFrame((_, delta) => {
391    // Animate particles
392    for (let i = 0; i < count; i++) {
393      positions.current[i * 3 + 1] -= delta * 2;
394      if (positions.current[i * 3 + 1] < -25) {
395        positions.current[i * 3 + 1] = 25;
396      }
397    }
398    ref.current.geometry.attributes.position.needsUpdate = true;
399  });
400 
401  return (
402    <points ref={ref}>
403      <bufferGeometry>
404        <bufferAttribute
405          attach="attributes-position"
406          args={[positions.current, 3]}
407        />
408      </bufferGeometry>
409      <pointsMaterial color="#ffffff" size={0.2} sizeAttenuation />
410    </points>
411  );
412}
413```
414 
415## Touch Controls (Orbit)
416 
417See the full `orbit-controls.tsx` implementation in the lib files. Usage:
418 
419```tsx
420import { View } from "react-native";
421import { FiberCanvas } from "@/lib/fiber-canvas";
422import useControls from "@/lib/orbit-controls";
423 
424function Scene() {
425  const [OrbitControls, events] = useControls();
426 
427  return (
428    <View style={{ flex: 1 }} {...events}>
429      <FiberCanvas style={{ flex: 1 }}>
430        <OrbitControls />
431        {/* Your 3D content */}
432      </FiberCanvas>
433    </View>
434  );
435}
436```
437 
438## Common Issues & Solutions
439 
440### 1. "X is not part of the THREE namespace"
441 
442**Problem:** Error like `AmbientLight is not part of the THREE namespace`
443 
444**Solution:** Add the missing component to the `extend()` call in fiber-canvas.tsx:
445 
446```tsx
447extend({
448  AmbientLight: THREE.AmbientLight,
449  // Add other missing components...
450});
451```
452 
453### 2. TypeScript Errors with Three.js
454 
455**Problem:** Type mismatches between three.js and R3F
456 
457**Solution:** Use `@ts-expect-error` comments where needed:
458 
459```tsx
460// @ts-expect-error - WebGPU renderer types don't match
461await state.gl.init();
462```
463 
464### 3. Blank Screen
465 
466**Problem:** Canvas renders but nothing visible
467 
468**Solution:**
469 
4701. Ensure camera is positioned correctly and looking at scene
4712. Add lighting (objects are black without light)
4723. Check that `extend()` includes all components used
473 
474### 4. Performance Issues
475 
476**Problem:** Low frame rate or stuttering
477 
478**Solution:**
479 
480- Reduce polygon count in geometries
481- Use `useMemo` for static data
482- Limit particle count
483- Use `instancedMesh` for many identical objects
484 
485### 5. Peer Dependency Errors
486 
487**Problem:** npm install fails with ERESOLVE
488 
489**Solution:** Use `--legacy-peer-deps`:
490 
491```bash
492npm install <packages> --legacy-peer-deps
493```
494 
495## Building
496 
497WebGPU requires a custom build:
498 
499```bash
500npx expo prebuild
501npx expo run:ios
502```
503 
504**Note:** WebGPU does NOT work in Expo Go.
505 
506## File Structure
507 
508```
509src/
510├── app/
511│   └── index.tsx           # Entry point with lazy loading
512├── components/
513│   ├── scene.tsx           # Main 3D scene
514│   └── game.tsx            # Game logic
515└── lib/
516    ├── fiber-canvas.tsx    # R3F canvas wrapper
517    ├── make-webgpu-renderer.ts  # WebGPU renderer
518    └── orbit-controls.tsx  # Touch controls
519```
520 
521## Decision Tree
522 
523```
524Need 3D graphics?
525├── Simple shapes → mesh + geometry + material
526├── Animated objects → useFrame + refs
527├── Many objects → instancedMesh
528├── Particles → Points + BufferGeometry
529│
530Need interaction?
531├── Orbit camera → useControls hook
532├── Touch objects → onClick on mesh
533├── Gestures → react-native-gesture-handler
534│
535Performance critical?
536├── Static geometry → useMemo
537├── Many instances → InstancedMesh
538└── Complex scenes → LOD (Level of Detail)
539```
540 
541## Example: Complete Game Scene
542 
543```tsx
544import * as THREE from "three/webgpu";
545import { View, Text, Pressable } from "react-native";
546import { useRef, useState, useCallback } from "react";
547import { useFrame, useThree } from "@react-three/fiber";
548import { FiberCanvas } from "@/lib/fiber-canvas";
549 
550function Player({ position }: { position: THREE.Vector3 }) {
551  const ref = useRef<THREE.Mesh>(null!);
552 
553  useFrame(() => {
554    ref.current.position.copy(position);
555  });
556 
557  return (
558    <mesh ref={ref}>
559      <coneGeometry args={[0.5, 1, 8]} />
560      <meshStandardMaterial color="#00ffff" />
561    </mesh>
562  );
563}
564 
565function GameScene({ playerX }: { playerX: number }) {
566  const { camera } = useThree();
567  const playerPos = useRef(new THREE.Vector3(0, 0, 0));
568 
569  playerPos.current.x = playerX;
570 
571  useEffect(() => {
572    camera.position.set(0, 10, 15);
573    camera.lookAt(0, 0, 0);
574  }, [camera]);
575 
576  return (
577    <>
578      <ambientLight intensity={0.5} />
579      <directionalLight position={[5, 10, 5]} />
580      <Player position={playerPos.current} />
581    </>
582  );
583}
584 
585export default function Game() {
586  const [playerX, setPlayerX] = useState(0);
587 
588  return (
589    <View style={{ flex: 1, backgroundColor: "#000" }}>
590      <FiberCanvas style={{ flex: 1 }}>
591        <GameScene playerX={playerX} />
592      </FiberCanvas>
593 
594      <View style={{ position: "absolute", bottom: 40, flexDirection: "row" }}>
595        <Pressable onPress={() => setPlayerX((x) => x - 1)}>
596          <Text style={{ color: "#fff", fontSize: 32 }}>◀</Text>
597        </Pressable>
598        <Pressable onPress={() => setPlayerX((x) => x + 1)}>
599          <Text style={{ color: "#fff", fontSize: 32 }}>▶</Text>
600        </Pressable>
601      </View>
602    </View>
603  );
604}
605```
606