WebGPURenderer: Fix global references in Node.js #29919

whatisor · 2024-11-19T02:32:12Z

Description
Fix compilation issue on react.

github-actions · 2024-11-19T02:35:07Z

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	339.13 79	339.13 79	+0 B +0 B
WebGPU	484.71 134.2	484.87 134.24	+156 B +45 B
WebGPU Nodes	484.18 134.1	484.34 134.14	+156 B +44 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	464.59 111.96	464.59 111.96	+0 B +0 B
WebGPU	552.01 149.42	552.17 149.47	+156 B +44 B
WebGPU Nodes	507.89 139.13	508.05 139.18	+156 B +44 B

src/renderers/webgpu/WebGPUBackend.js

src/renderers/webgpu/nodes/WGSLNodeBuilder.js

src/renderers/webgpu/utils/WebGPUUtils.js

donmccurdy · 2024-11-19T12:55:50Z

Note – I've renamed the issue to "fix global references in Node.js". I think that's the issue here, not React. Next.js is a React-based framework that happens to execute code in both a browser environment and server-side in Node.js.

Mugen87 · 2024-11-19T14:43:19Z

src/renderers/webgpu/WebGPUBackend.js

@@ -64,7 +64,7 @@ class WebGPUBackend extends Backend {
 				powerPreference: parameters.powerPreference
 			};

-			const adapter = await navigator.gpu.requestAdapter( adapterOptions );
+			const adapter = ( typeof navigator !== 'undefined' ) ? await navigator.gpu.requestAdapter( adapterOptions ) : {};


@donmccurdy{} is intended as a workaround for node but I'm not sure {} is ideal here. Do you think this use case is handled appropriately or would you implement it in a different way?

Base on that function code, it should be null, otherwise, next step is exceptional?
"adapter.features"

@whatisor are you executing this code in the Node.js environment and seeing runtime errors, or is this a compile-time error (like from TypeScript or Webpack)? Not clear to me from #29916.

I'm not sure that backend.init( renderer ) should be making efforts to avoid runtime exceptions, if running in an environment where neither WebGL nor WebGPU exists. I would support fixes that avoid build-time errors, and run-time errors in module scope. But if you are initializing and using a renderer in Node.js, a runtime exception is to be expected.

I'm not sure that backend.init( renderer ) should be making efforts to avoid runtime exceptions, if running in an environment where neither WebGL nor WebGPU exists

I agree, I think we should be throwing an error here, it doesn't make much sense to me to proceed with an empty object as an adapter.

@donmccurdy it is compile error.
We also need to fix three\examples\jsm\capabilities\WebGPU.js with global and await.
So, we should return null and (exception is next step as current)?

three\examples\jsm\capabilities\WebGPU.js

Capabilities should be optional, it should be possible to use WebGPURenderer without global await. #29218

can we do same thing with webgl to avoid await?
https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext

=> No, we still need to await for real adapter. I guess browser need to improve this part.

Use `null` as fallback when navigator isn't available.

sunag · 2024-11-20T01:03:14Z

src/renderers/webgpu/utils/WebGPUUtils.js

@@ -113,13 +113,21 @@ class WebGPUUtils {
 		// TODO: Remove this check when Quest 34.5 is out
 		// https://github.com/mrdoob/three.js/pull/29221/files#r1731833949

-		if ( navigator.userAgent.includes( 'Quest' ) ) {
+		if ( typeof navigator !== 'undefined' ) {


Could we remove this? It is inside a function that will never be executed by the adapter return null in this case.

I guess the issue is that it's a compiler error, not a runtime error? I wish we knew what in the Next.js stack is doing compile-time checks on dependencies, and what its requirements are. Avoiding all references to browser globals is a pretty tall order for a large library relying heavily on Web APIs. :/

The compiler throwing an error for a global variable inside a function seems strange to say the least, since a variable can be declared at the global level after the function declaration.

Yeah, I'm not sure why... trying to reproduce the issue:

Improve compatibility of three/webgpu with nextjs #29916 (comment)

I think it is this one:
https://react.dev/reference/react/StrictMode

verekia · 2024-11-21T08:58:21Z

I have set up a test suite of various build environments, like Vite, with and without React, Next.js, R3F, and a specific one to check this PR: https://github.com/verekia/three-gpu-ecosystem-tests

The PR does indeed fix Next.js crashing on reference errors 🙌 That being said, I am getting a Multiple instances of Three.js being imported warning, which I don't get when importing WebGPURenderer dynamically. Maybe @CodyJasonBennett would have insights on why that happens.

Regular import (fixed by this PR):
next-pages-vanilla-pr-29919/pages/index.js

Dynamic import workaround:
next-pages-vanilla-dynamic-8ce69e0/pages/index.js

Mugen87 · 2024-11-23T22:26:30Z

It seems the only blocking bit is the change in WebGPUUtils.

@verekia Can you please verify if build works without this change? If so, we can revert it ( see #29919 (comment)).

verekia · 2024-11-24T08:39:18Z

Yes, it works without the WebGPUUtils change. I added the test case to my repo.

Revert.

Mugen87 · 2024-11-24T09:31:21Z

Thanks for letting us know! I have reverted the changes in WebGPUUtils so it seems the PR is ready to go.

whatisor · 2024-11-24T15:05:28Z

Thanks for letting us know! I have reverted the changes in WebGPUUtils so it seems the PR is ready to go.
@Mugen87 We still need to update WebGPUtils and examples because people stills use it from example and it will not be able to compile, don't we?

verekia · 2024-11-24T15:50:51Z

@whatisor Could you provide a repro where WebGPUUtils causes a crash in a Next.js project?

My test is pretty basic, the only thing I import is:

import * as THREE from 'three'
import { WebGPURenderer } from 'three/webgpu'

CodyJasonBennett · 2024-11-24T15:56:09Z

This PR has nothing to do with React or its strict mode etc. We need a reproduction to know what's going on here or if this is something we can actually support. Next is notorious for overzealous compilation the ecosystem itself can't mitigate.

whatisor · 2024-11-24T23:38:17Z

@whatisor Could you provide a repro where WebGPUUtils causes a crash in a Next.js project?

My test is pretty basic, the only thing I import is:
import * as THREE from 'three'
import { WebGPURenderer } from 'three/webgpu'

I did not mean issue of Core. It is just simply call Webgpu.isAvailable() in your test to see compilation issue, but I will push PR to your test case

verekia · 2024-11-25T03:47:11Z

@whatisor You are not supposed to call any method that's meant for browsers during SSR. These should live in a useEffect or similar. See this classic article about hydration.

WebGPU.isAvailable() // ❌ Don't do that, it runs on the server during SSR

function MyComponent() {
  WebGPU.isAvailable() // ❌ Don't do that, it runs on the server during SSR

  useEffect(() => {
    WebGPU.isAvailable() // ✅ No problem, runs only in the browser
  }, [])

  return // ...
}

That's why the only concern for Three.js should be that importing in a Next.js project doesn't cause a crash due to global browser variable access and top-level browser API calls. If you call methods during SSR that should never run on the server, then it's expected for SSR to break.

verekia · 2024-11-25T07:54:57Z

I added more test cases to my repo, including Next 14/15, React 18/19, Pages/App router, and a TSL call for all cases. Now that this PR is merged, things are looking really good for Next.js support in r171. Thank you.

✅ Vite + vanilla Three.js: Works in all cases.

✅ Next.js + vanilla Three.js: Works in all cases.

✅ Vite + R3F: Works.

✅ Next.js 14 + R3F: Works in both Pages and App routers.

❌ Next.js 15 + R3F: Does not work, except with Pages Router + React 18.

The recent release of Next.js 15 + React 19 RC is expected to break things on the R3F side, so it's not a problem Three.js should worry about.

whatisor · 2024-11-25T15:11:38Z

  useEffect(() => {
    WebGPU.isAvailable() // ✅ No problem, runs only in the browser
  }, [])

I added into your 2 test cases and it is failed from BUILD step.

Thank @Mugen87 because of removing self but still issue with nagivator and warning with await.

whatisor · 2024-11-25T15:14:45Z

https://github.com/whatisor/three-gpu-ecosystem-tests/blob/main/next-14-pages-r3f-react-18/pages/index.js

verekia · 2024-11-25T15:25:24Z

You're right @whatisor, this navigator is at the top-level, so it will break imports. The one we reverted in WebGPUUtils was not top-level, as it was in a class method. Let's keep hunting down only the top-level ones :)

Mugen87 · 2024-11-25T15:28:40Z

I guess we can simply do the following?

let isAvailable = ( typeof navigator !== 'undefined'  && navigator.gpu !== undefined );

It does not matter that isAvailable ends up false, right? This is just a compile issue.

Mugen87 · 2024-11-25T15:45:29Z

and warning with await.

How does this warning look like? Is it still possible to compile your code with the below await usage?

three.js/examples/jsm/capabilities/WebGPU.js

Line 6 in 4749f99

isAvailable = await navigator.gpu.requestAdapter();

verekia · 2024-11-25T15:54:20Z

It compiles with this warning:

   ▲ Next.js 15.0.3

 ✓ Linting and checking validity of types    
   Creating an optimized production build ...
 ⚠ Compiled with warnings

./node_modules/three/examples/jsm/capabilities/WebGPU.js
The generated code contains 'async/await' because this module is using "topLevelAwait".
However, your target environment does not appear to support 'async/await'.
As a result, the code may not run as expected or may cause runtime errors.

Import trace for requested module:
./node_modules/three/examples/jsm/capabilities/WebGPU.js

 ✓ Compiled successfully

I am on Node v22.10.0, and interestingly, I was not getting the ReferenceError because navigator is actually defined in that version. I switched to Node 18 and it's not defined. Anyway, I think it's a good practice to do these typeof checks for navigator, window, and other global browser objects.

Mugen87 · 2024-11-25T18:58:11Z

I think we can live with that warning for now.

verekia · 2024-11-26T03:00:49Z

navigator was added in Node 21

verekia · 2024-11-26T09:32:50Z

After another full day of testing and Dockerizing for more reliable reproductions, I have updated the repo with new findings. I have added an import of capabilities/WebGPU.js and call to isAvailable in all cases.

The main takeaway on the Three.js side is that importing top-level await modules such as capabilities/WebGPU.js does break Vite's default config, and causes that warning we discussed above in Next.js, both in the browser console and at compilation.

You can test it easily:

cd vite-vanilla-js
Comment out optimizeDeps and build.target in vite.config.js
npm run docker (or npm i && npm start if you don't have Docker)

Or Next.js:

cd next15-pages-vanilla-react19
npm run docker (or npm i && npm start)

whatisor · 2024-11-27T03:30:27Z

Yeah, I still need to implement my own WebGPU async checking anyway. Because cannot risky update everything to latest.

Fix compilation in react

df963e1

sunag changed the title ~~Fix compilation in react~~ WebGPURenderer: Fix compilation in react Nov 19, 2024

sunag added this to the r171 milestone Nov 19, 2024

Mugen87 reviewed Nov 19, 2024

View reviewed changes

src/renderers/webgpu/WebGPUBackend.js Outdated Show resolved Hide resolved

Mugen87 reviewed Nov 19, 2024

View reviewed changes

src/renderers/webgpu/nodes/WGSLNodeBuilder.js Outdated Show resolved Hide resolved

Mugen87 reviewed Nov 19, 2024

View reviewed changes

src/renderers/webgpu/nodes/WGSLNodeBuilder.js Outdated Show resolved Hide resolved

Mugen87 reviewed Nov 19, 2024

View reviewed changes

src/renderers/webgpu/utils/WebGPUUtils.js Outdated Show resolved Hide resolved

donmccurdy changed the title ~~WebGPURenderer: Fix compilation in react~~ WebGPURenderer: Fix global references in Node.js Nov 19, 2024

whatisor added 3 commits November 19, 2024 09:34

Cleanup fixes

1cb2183

Fix space

0b09367

Fix space

78800ae

Mugen87 reviewed Nov 19, 2024

View reviewed changes

Update WebGPUBackend.js

a32f487

Use `null` as fallback when navigator isn't available.

Mugen87 approved these changes Nov 19, 2024

View reviewed changes

sunag reviewed Nov 20, 2024

View reviewed changes

Update WebGPUUtils.js

07c95d6

Revert.

Mugen87 merged commit 927c20c into mrdoob:dev Nov 24, 2024
12 checks passed

Mugen87 mentioned this pull request Nov 25, 2024

Add webgpu async check #29927

Closed

Mugen87 mentioned this pull request Nov 25, 2024

WebGPU: Fix navigator usage. #29965

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WebGPURenderer: Fix global references in Node.js #29919

WebGPURenderer: Fix global references in Node.js #29919

whatisor commented Nov 19, 2024 •

edited by Mugen87

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading

donmccurdy commented Nov 19, 2024

Mugen87 Nov 19, 2024 •

edited

Loading

whatisor Nov 19, 2024

donmccurdy Nov 19, 2024 •

edited

Loading

sunag Nov 19, 2024

whatisor Nov 19, 2024

sunag Nov 20, 2024

whatisor Nov 20, 2024 •

edited

Loading

sunag Nov 20, 2024

donmccurdy Nov 20, 2024 •

edited

Loading

sunag Nov 20, 2024

donmccurdy Nov 20, 2024

whatisor Nov 20, 2024

verekia commented Nov 21, 2024

Mugen87 commented Nov 23, 2024

verekia commented Nov 24, 2024

Mugen87 commented Nov 24, 2024

whatisor commented Nov 24, 2024

verekia commented Nov 24, 2024

CodyJasonBennett commented Nov 24, 2024

whatisor commented Nov 24, 2024

verekia commented Nov 25, 2024 •

edited

Loading

verekia commented Nov 25, 2024 •

edited

Loading

whatisor commented Nov 25, 2024

whatisor commented Nov 25, 2024

verekia commented Nov 25, 2024

Mugen87 commented Nov 25, 2024 •

edited

Loading

Mugen87 commented Nov 25, 2024

verekia commented Nov 25, 2024

Mugen87 commented Nov 25, 2024

verekia commented Nov 26, 2024

verekia commented Nov 26, 2024

whatisor commented Nov 27, 2024

WebGPURenderer: Fix global references in Node.js #29919

WebGPURenderer: Fix global references in Node.js #29919

Conversation

whatisor commented Nov 19, 2024 • edited by Mugen87 Loading

github-actions bot commented Nov 19, 2024 • edited Loading

📦 Bundle size

🌳 Bundle size after tree-shaking

donmccurdy commented Nov 19, 2024

Mugen87 Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

donmccurdy Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whatisor Nov 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

donmccurdy Nov 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

verekia commented Nov 21, 2024

Mugen87 commented Nov 23, 2024

verekia commented Nov 24, 2024

Mugen87 commented Nov 24, 2024

whatisor commented Nov 24, 2024

verekia commented Nov 24, 2024

CodyJasonBennett commented Nov 24, 2024

whatisor commented Nov 24, 2024

verekia commented Nov 25, 2024 • edited Loading

verekia commented Nov 25, 2024 • edited Loading

whatisor commented Nov 25, 2024

whatisor commented Nov 25, 2024

verekia commented Nov 25, 2024

Mugen87 commented Nov 25, 2024 • edited Loading

Mugen87 commented Nov 25, 2024

verekia commented Nov 25, 2024

Mugen87 commented Nov 25, 2024

verekia commented Nov 26, 2024

verekia commented Nov 26, 2024

whatisor commented Nov 27, 2024

whatisor commented Nov 19, 2024 •

edited by Mugen87

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading

Mugen87 Nov 19, 2024 •

edited

Loading

donmccurdy Nov 19, 2024 •

edited

Loading

whatisor Nov 20, 2024 •

edited

Loading

donmccurdy Nov 20, 2024 •

edited

Loading

verekia commented Nov 25, 2024 •

edited

Loading

verekia commented Nov 25, 2024 •

edited

Loading

Mugen87 commented Nov 25, 2024 •

edited

Loading