r3f-setup（r3f 设置）

Project Setup

Set up a React Three Fiber project with WebGPU support using React 19 and Three.js TSL.

Dependencies

Core dependencies for R3F with WebGPU:

{
  "dependencies": {
    "@react-three/drei": "11.0.0-alpha.4",
    "@react-three/fiber": "10.0.0-alpha.1",
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "three": "0.182.0"
  },
  "devDependencies": {
    "@types/three": "0.182.0"
  },
  "overrides": {
    "three": "0.182.0"
  }
}

Canvas Setup

Import Canvas from the WebGPU entry point:

import { Canvas } from '@react-three/fiber/webgpu'

const App = () => (
  <Canvas>
    <mesh>
      <boxGeometry />
      <meshBasicMaterial color="red" />
    </mesh>
  </Canvas>
)

TSL Shaders

For custom shaders, use Three.js TSL (Three Shading Language):

import { Fn, vec3, sin, time } from 'three/tsl'

Use node materials like meshBasicNodeMaterial for TSL integration.

TypeScript Declarations

Create r3f.d.ts in your project (at the root for example) for proper typings:

import type { ThreeToJSXElements } from '@react-three/fiber'
import type * as THREE from 'three/webgpu'

declare module '@react-three/fiber' {
  interface ThreeElements extends ThreeToJSXElements<typeof THREE> {}
}

This enables R3F element's typings. Make sure it's part of the files included in your tsconfig.json.

Required Patches (Bun)

Three.js 0.182.0 and detect-gpu require patches for WebGPU/SSR compatibility. Add to package.json:

{
  "patchedDependencies": {
    " [email protected] ": "patches/ [email protected] ",
    " [email protected] ": "patches/ [email protected] "
  }
}

Create patches/ [email protected] (fixes GPUShaderStage SSR error):

diff --git a/build/three.webgpu.js b/build/three.webgpu.js
index 31ff163d67f4cc5dec060a11bc7151c64f949fd9..823c1c35bca5411a27cbf52c5c3a188001fe0445 100644
--- a/build/three.webgpu.js
+++ b/build/three.webgpu.js
@@ -70604,7 +70604,7 @@ const GPUPrimitiveTopology = {
 	TriangleStrip: 'triangle-strip',
 };

-const GPUShaderStage = ( typeof self !== 'undefined' ) ? self.GPUShaderStage : { VERTEX: 1, FRAGMENT: 2, COMPUTE: 4 };
+const GPUShaderStage = ( typeof self !== 'undefined' && self.GPUShaderStage ) ? self.GPUShaderStage : { VERTEX: 1, FRAGMENT: 2, COMPUTE: 4 };

 const GPUCompareFunction = {
 	Never: 'never',

Create patches/ [email protected] (adds missing exports field):

diff --git a/package.json b/package.json
index 22ffa92b457c0d83c052eab3f1961110d134d1b3..4f5f9ef7a8a80d6f85e3e5b241a87091d95bbe39 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,12 @@
   "main": "dist/detect-gpu.umd.js",
   "module": "dist/detect-gpu.esm.js",
   "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/detect-gpu.esm.js",
+      "require": "./dist/detect-gpu.umd.js"
+    }
+  },
   "homepage": "https://github.com/pmndrs/detect-gpu#readme",
   "bugs": {
     "url": "https://github.com/pmndrs/detect-gpu/issues"

Run bun install to apply patches.

Key Notes

• R3F v10 and Drei v11 are currently in alpha for WebGPU support
• Use three-stdlib for additional utilities
• React Compiler is recommended with React 19
• The overrides field ensures consistent Three.js versions across dependencies

This skill is part of verekia's r3f-gamedev.