Node Worker not started in DEV mode

[aheissenberger]

Describe the bug

Works with pnpm build and pnpm start but fails pnpm dev:

Error: Not running in a worker thread - Click to expand the full error!

[react-server] Ctrl+C to exit 🚫
[react-server] Not running in a worker thread
[react-server]   [stack]: Error: Not running in a worker thread
[react-server]     at /rs-bug-node-worker/src/DEMO/api-worker.ts:4:9
[react-server]     at ESModulesEvaluator.runInlinedModule (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1062:5)
[react-server]     at RSCModuleRunner.directRequest (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1284:61)
[react-server]     at RSCModuleRunner.cachedRequest (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1180:76)
[react-server]     at /rs-bug-node-worker/src/DEMO/api.ts:1:1
[react-server]     at ESModulesEvaluator.runInlinedModule (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1062:5)
[react-server]     at RSCModuleRunner.directRequest (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1284:61)
[react-server]     at RSCModuleRunner.cachedRequest (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1180:76)
[react-server]     at /rs-bug-node-worker/src/App.tsx:5:1
[react-server]     at ESModulesEvaluator.runInlinedModule (file:///rs-bug-node-worker/node_modules/.pnpm/rolldown-vite@6.3.5_@types+node@20.19.11_esbuild@0.25.9_jiti@1.21.7_sass@1.90.0_terser@_d4d69b3d57cfb5ebe5fd478306091e9d/node_modules/rolldown-vite/dist/node/module-runner.js:1062:5)

I prepared an example repository with the problem:
https://github.com/aheissenberger/rs-bug-node-worker

All relevant files have a comment // DEMO included:

• /src/DEMO - here is a demo api and the worker
• src/App.tsx - server page which calls the api and starts the worker
• vite.config.ts - build using the vite plugin @fetsorn/vite-node-worker

Is there a better place to start the worker on start of the application and a better way to provide the api?

Reproduction

https://github.com/aheissenberger/rs-bug-node-worker

Steps to reproduce

No response

System Info

System:
    OS: macOS 15.6.1
    CPU: (12) arm64 Apple M4 Pro
    Memory: 2.93 GB / 48.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.6.0 - /opt/homebrew/bin/node
    Yarn: 1.22.22 - /opt/homebrew/bin/yarn
    npm: 11.5.1 - /opt/homebrew/bin/npm
    pnpm: 10.15.0 - /opt/homebrew/bin/pnpm
    bun: 1.2.20 - /opt/homebrew/bin/bun
  npmPackages:
    @lazarv/react-server: 0.0.0-experimental-2dab5bb-20250522-222c3bcf => 0.0.0-experimental-2dab5bb-20250522-222c3bcf 
    @lazarv/react-server-adapter-vercel: 0.0.0-experimental-138ef89-20241217-08cf78b6 => 0.0.0-experimental-138ef89-20241217-08cf78b6 
    vite: ^6.3.5 => 6.3.5

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.

[lazarv]

The issue in the demo is that @fetsorn/vite-node-worker is a build-only Vite plugin, as it is using apply: 'build' and Rollup/Rolldown specific API like this.emitFile. Also this plugin is not aware about Vite Environment API, and this should only be applied on the rsc environment. So this will not work in development mode. 'use worker' incoming feature request? I would really like the idea.

[aheissenberger]

I filed and fixed the plugin to support DEV and BUILD mode and included support for using alias in workers:
https://github.com/aheissenberger/vite-plugin-node-worker

Without the alias resolution the problem was easy to solve in DEV mode. Having a builtin 'use worker' directive sounds cool :-)
And I am sure with your knowledge about the Vite Environment API this should be easy.

Should I move to start the worker in the react-server runtime and share the api per context or should I stay with current approach where the worker starts lazy on the first call to the api?

[lazarv]

Nice! There's only one issue with the worker file. The build emits the file outside of the .react-server/server directory, into .react-server, and a deploy adapter will not copy the worker file, as it only copies from the server directory.

Using a worker with server components introduces a problem: when to terminate the worker. If the worker is request-specific and should be short-lived and should be terminated when sending the response, then I would start the worker in a middleware instead of a server component. If the worker has a lifetime tied to the server instance, then it should be created using the runtime context, like the SSR worker created by the framework.

I actually started to work on 'use worker' as this is a fun feature! It already feels much more native to the framework, and it is in fact very easy to utilize the Vite Environment API to handle all the module resolution in the worker. I need some more time to polish it for a proper release, but it will be available very soon!

[aheissenberger]

My use case is similar to your SSR worker, I had to move my event source writer to its own thread to stop it blocking all other requests when I hammered it with a huge amount of events which needed to be saved sequential to a disk store.

When deploying to a distributed system (e.g. AWS Lambda) my architecture would change by not using a worker but a Lambda connected to an AWS SQS Queue as a single fanout for my use case. Your use case for SSR worker is different as there is no need to spin up workers as the API Gateway would do it for you and the main process cannot be overwhelmed with SSR requests.

When you design 'use worker', you might need an abstract way the communication too to allow a deployment adapter to decide on how to split, bundle and ship these parts. The really complex thing starts when looking at cloud functions which are not node based and which do not support workers compared to lambda where a worker is possible. An other aspect is the fact that workers similar to node server can be stateful for the lifetime where cloud functions have a single request model.

Keep in mind that I deployed react-server to lambda, but because of the cold start time of react-server starting up workers and caching, the response times where much higher compared to other react server frameworks. I know that the time spent in the initial phase gives later much better response timings in a node server environment but a lambda has a defined lifetime which and when scaling up many people can hit cold starts immediately. When possible a deployment adapter can split the server code for lambda in the server code which only get initialized once and lives outside the event loop and can be stateful for the lifetime of the lambda receiving further requests.

On my framework level I hide the different deployment requirements with a runtime setup file which is different per deployment target. For this it might be useful for an application to have a mechanism to at least mark modules specific to a deployment adapter or provide an entry point which is different pro deployment adapter and is used to setup the runtime context.

[lazarv]

I would use a full-fledged solution even for local development. A simple worker thread is far from ideal for an event source managing system.

'use worker' for me is only for handling a Node.js worker thread in server components, to run something more CPU-intensive, but with tight integration with the framework. It's not a worker pool running arbitrary tasks, as there are better solutions for implementing such parts of an application, both locally and in the cloud. The worker thread, with the 'use worker' directive, has a direct communication channel to the main thread. The final part of this feature I'm working on now is to utilize the same React server-side rendering features in the worker as in server components, with communication based on RSC, streamed both ways. This simplifies working with asynchronous data streams on the worker, allowing the result to be used seamlessly in a server component. This is essentially an internal worker-thread-based solution for RSC federation, similar to how <RemoteComponent> works, but much easier to implement, as it's the same application.

Based on the above, I do not plan to provide any deployment-specific abstraction for the 'use worker' feature. If you would like to move the worker outside of the main application in a cloud environment, then move that part outside of the application code, into another application or service.

Regarding the performance of @lazarv/react-server in a cloud environment, proper instrumentation is essential to accurately profile what takes up time during cold starts and requests. Performance when using a worker is definitely tied to the available vCPUs and memory, but I have more prominent suspects for performance issues. Still, @lazarv/react-server performs basically the best out of all frameworks with the same approach and using Node.js. I'm planning to publish all my benchmarking results in a longer article about web performance (TTFB, FCP, LCP, hydration, etc.), but I need to be very diplomatic there and watch what I say, as I don't intend to start a drama.

A deployment adapter can easily provide a stripped-down version of what @lazarv/react-server needs in production. Most of the code in the production mode server is unnecessary in a serverless deployment, and you only need to run the SSR renderer with some initial context setup, which is about 20% of the production server, which is only a few hundred lines long. Everything is accessible from the framework. There are no internals that are not available, and I would consider most parts simple to use.

I'm sure I will eventually get back to your AWS adapter PR and help with finishing it, providing support in solving any performance issues. I would be really disappointed if it were not available this year as an MVP, even with only a few months left and so many distractions.

[aheissenberger]

I will use some time tomorrow to look at the deployment adapter for aws.

[lazarv]

Don't rush it! I'm pretty busy with another project at the moment.

[lazarv]

This was implemented in #312 and documentation about 'use worker' can be found at https://react-server.dev/framework/worker.

[github-actions]

This issue has been locked since it has been closed for more than 30 days.

If you have found a concrete bug or regression related to it, please open a new bug report with a reproduction against the latest version of @lazarv/react-server. If you have any other comments you should create a new discussion.