From 2dbe3713087d60a1cf79f2c505ec7f73cc38e9a1 Mon Sep 17 00:00:00 2001
From: huymobile <kingonwork@gmail.com>
Date: Mon, 24 Aug 2026 09:40:59 +0700
Subject: [PATCH] docs: clarify when Three.js needs Metro aliases

---
 apps/docs/content/docs/getting-started/expo.mdx  | 2 ++
 apps/docs/content/docs/integrations/three-js.mdx | 8 +++++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/apps/docs/content/docs/getting-started/expo.mdx b/apps/docs/content/docs/getting-started/expo.mdx
index 9b4df58a9..8676778a7 100644
--- a/apps/docs/content/docs/getting-started/expo.mdx
+++ b/apps/docs/content/docs/getting-started/expo.mdx
@@ -13,6 +13,8 @@ npx create-expo-app@latest -e with-webgpu
 
 The template includes `react-native-webgpu`, Reanimated, and Metro settings compatible with Three.js WebGPU builds.
 
+For a raw Three.js integration that imports `three/webgpu` directly, recent Expo and Metro versions can resolve that package export without a custom resolver. The template keeps additional Metro settings because it also redirects bare `three` imports and selects the standard React Three Fiber build. See the [Three.js integration guide](/docs/integrations/three-js) before copying those settings into an existing app.
+
 For a walkthrough of the template, watch the video below.
 
 <Video src="/videos/expo-template.mp4" />
diff --git a/apps/docs/content/docs/integrations/three-js.mdx b/apps/docs/content/docs/integrations/three-js.mdx
index 3fbcea4fa..f8c51899a 100644
--- a/apps/docs/content/docs/integrations/three-js.mdx
+++ b/apps/docs/content/docs/integrations/three-js.mdx
@@ -7,10 +7,12 @@ Using the Three.js WebGPU backend, you can run the library on top of React Nativ
 
 <WebGPUPlayground demo="three-js" height={280} />
 
-## 1. Metro configuration
+## 1. Import the WebGPU entry point
 
 Three.js publishes separate WebGL and WebGPU entry points.
-Metro must load `build/three.webgpu.js` when you import `three` or `three/webgpu`. See [Expo setup](/docs/getting-started/expo) for a complete Metro configuration:
+With current Expo and Metro versions, importing `three/webgpu` resolves Three.js's WebGPU package export directly and does not require a custom Metro configuration.
+
+Add a resolver override only when your setup needs one—for example, an older Metro version cannot resolve the package export, a monorepo resolves a different copy of Three.js, or a dependency imports bare `three` and must be redirected to the WebGPU build. The example app uses the following fallback because it covers those cases and React Three Fiber:
 
 ```js
 // metro.config.js - resolveRequest excerpt
@@ -31,7 +33,7 @@ if (moduleName.startsWith("three/addons/")) {
 }
 ```
 
-Import from `three/webgpu`, not `three` (which would pull the WebGL build).
+Start with an explicit import from `three/webgpu`, not `three` (which would pull the WebGL build without the optional redirect above). If that import resolves in your project, keep the default Metro configuration.
 
 ## 2. Create the renderer