feat: add vite client connect events #20978

sapphi-red · 2025-10-22T05:15:30Z

Description

Added vite:client-connect / vite:client-disconnect events so that it's possible to track the client life-cycle. This is needed for full bundle mode to properly trigger HMR (we have the same issue in unbundled mode as well, but it wasn't a big problem). This is probably needed to solve #19710 as well.
This API is also useful for vite-dev-rpc to migrate to environment.hot.

hi-ogawa

Looks good to me. Should we update docs to mention this? I see currently there is an example like server.on('connection', ...). The difference from current hot.on("connection" ...) should be probably mentioned too or how it can be entirely replaced? (and that's something I'm actually confused about)

packages/vite/src/node/server/ws.ts

bluwy · 2025-10-23T06:35:36Z

packages/vite/types/customEvent.d.ts

+  // server events
+  'vite:client-connect': undefined
+  'vite:client-disconnect': undefined


Should we rename it as vite:client:connect so it's similar to vite:ws:connect?

Btw I found it initially weird that we're mixing client/server events here, but it's not too terrible at the end if it makes configuring events easier. It's unlikely that client <-> server with the same event name will need different payload shape.

pkg-pr-new · 2025-10-23T06:42:01Z

Open in StackBlitz

npm i https://pkg.pr.new/vite@20978

commit: 541e945

sapphi-red · 2025-10-23T07:00:18Z

Should we update docs to mention this? I see currently there is an example like server.on('connection', ...). The difference from current hot.on("connection" ...) should be probably mentioned too or how it can be entirely replaced? (and that's something I'm actually confused about)

The difference is only the callback parameter. connection event has (this: Server<T>, socket: T, request: IncomingMessage) => void as a callback for env that uses the builtin WebSocket channel, and () => void for other channels.
I'll update the docs.

hi-ogawa · 2025-10-23T07:06:25Z

For custom hmr channel/transport, I think the mechanism of emitting vite:... needs to be explicitly implemented on their side.

docs/guide/api-environment-plugins.md

docs/guide/api-environment-runtimes.md

sapphi-red · 2025-10-23T08:04:34Z

Added the docs and renamed the event 👍

hi-ogawa

I don't think this is an issue but let me note one observation.

Currently, the default ssr environment server.environments.ssr.hot.on("vite:client:connect", ...) is triggered when server.environment.ssr.runner getter is accessed (or manually createServerModuleRunner is called) and the timing might look arbitrary. For example, one plugin can do ....ssr.hot.on("vite:client:connect" ...) during configureServer (like in the test) and other plugins might also grab ....ssr.runner during its configureServer.

For node worker example (which currently ignores vite:client:connect), I think the same can be said and the implementation might be able to allow somehow lazily spawning workers and also allow multiple workers with different entrypoints, If such implementation is possible, it probably makes sense to emit vite:client:connect for each module runner instantiation or entrypoint import on worker side. (I'm vaguely imagining how ?nodeWorker could be implemented #3932).

hi-ogawa · 2025-10-23T10:03:39Z

docs/guide/api-environment-runtimes.md

+      // client is already connected
+      if (event === 'connection' || event === 'vite:client:connect') return


Related to the last comment, I'm wondering if it's more natural to emit vite:client:connect from "client" side. For example, what does "server" side see if we add a following in worker.js above?

runner.hmrClient.send({ type: "custom", event: "vite:client:connected" })

Also what if we do the same in hmrClient.send(...) in @vite/client?

It would work for vite:client:connect but it won't work for vite:client:disconnect. I think it's better to handle them on the same side.

sapphi-red · 2025-10-24T02:39:07Z

the timing might look arbitrary

Indeed. I think I need to figure out when it should be emitted and probably how to handle the missed events (the clients connected before listening to the event). Solving #19710 should give me a better idea of how to handle it.

hi-ogawa · 2025-10-24T02:52:48Z

Somewhat related to missed events, would it make sense (or is it possible) to expose currently connected clients environment.hot.clients like current server.ws.clients?

sapphi-red · 2025-10-24T02:59:56Z

Yeah, I thought about that. I think it makes sense, but I'd like to leave that for now. (if you have a concrete usecase, we can add it now)

hi-ogawa · 2025-10-24T04:26:31Z

Leaving it out sounds good to me 👍 No use case in mind but was curious.

bluwy · 2025-10-24T06:04:25Z

The difference is only the callback parameter. connection event has (this: Server<T>, socket: T, request: IncomingMessage) => void as a callback for env that uses the builtin WebSocket channel, and () => void for other channels.

I'm reading the new docs and I'm still a bit confused between connection and vite:client:connect. It's not clear when connection gets emitted. So are they the same and should trigger at the same time? (with the different params) Though I'm also seeing that we're restricting the params via types:

vite/packages/vite/src/node/server/hmr.ts

Line 148 in ca18b23

on(event: 'connection', listener: () => void): void

If they are the same, should we deprecate the connection event? Or at least hide its exposure to the devs and prefer vite:client:connect instead? For APIs interacting with server.hot, this.environment.hot, etc I mean. For server.ws, I guess we have to keep it.

sapphi-red · 2025-10-24T07:26:51Z

I'm reading the new docs and I'm still a bit confused between connection and vite:client:connect. It's not clear when connection gets emitted. So are they the same and should trigger at the same time? (with the different params)

The connection event was vague about when it is emitted. Assuming that it follows the behavior of the connection event in server.ws, it should be emitted when the connection is established. The new vite:client:connect event has the same behavior (additionally this PR also clarified when it should be emitted), but with a different params. It's a new event because we cannot change the params of the connection event for server.ws. So, to sum up, connection event should be deprecated (updated).

bluwy

LGTM. Thanks for updating!

sapphi-red added 2 commits October 22, 2025 12:11

feat: add vite:client-connect and vite:client-disconnect

9be7c2a

feat: keep normalizedClient reference

a17beaf

sapphi-red added the p3-significant High priority enhancement (priority) label Oct 22, 2025

sapphi-red added this to the 7.2 milestone Oct 22, 2025

fix: emit event in server module runner transport correctly

72c7a92

sapphi-red requested a review from hi-ogawa October 23, 2025 02:58

hi-ogawa reviewed Oct 23, 2025

View reviewed changes

hi-ogawa added the trigger: preview label Oct 23, 2025

bluwy reviewed Oct 23, 2025

View reviewed changes

sapphi-red mentioned this pull request Oct 23, 2025

refactor: remove unused invoke parameter #20991

Merged

sapphi-red added 3 commits October 23, 2025 16:16

chore: merge main

0e2b635

refactor: rename vite:client-connect and vite:client-disconnect

5281282

docs: update

0fe5eb7

graphite-app bot reviewed Oct 23, 2025

View reviewed changes

docs/guide/api-environment-plugins.md Outdated Show resolved Hide resolved

docs/guide/api-environment-runtimes.md Outdated Show resolved Hide resolved

docs: update

863c3aa

hi-ogawa previously approved these changes Oct 23, 2025

View reviewed changes

hi-ogawa reviewed Oct 23, 2025

View reviewed changes

sapphi-red requested a review from bluwy October 24, 2025 03:00

docs: deprecate connection event

541e945

sapphi-red dismissed hi-ogawa’s stale review via 541e945 October 24, 2025 07:13

bluwy approved these changes Oct 25, 2025

View reviewed changes

hi-ogawa approved these changes Oct 27, 2025

View reviewed changes

sapphi-red merged commit 543d87c into vitejs:main Oct 27, 2025
17 checks passed

sapphi-red deleted the feat/add-vite-client-connect-events branch October 28, 2025 02:36

		// client is already connected
		if (event === 'connection' \|\| event === 'vite:client:connect') return

Uh oh!

feat: add vite client connect events #20978

feat: add vite client connect events #20978

Uh oh!

Conversation

sapphi-red commented Oct 22, 2025

Description

Uh oh!

hi-ogawa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bluwy Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sapphi-red commented Oct 23, 2025

Uh oh!

hi-ogawa commented Oct 23, 2025

Uh oh!

Uh oh!

Uh oh!

sapphi-red commented Oct 23, 2025

Uh oh!

hi-ogawa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

sapphi-red Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

sapphi-red commented Oct 24, 2025

Uh oh!

hi-ogawa commented Oct 24, 2025

Uh oh!

sapphi-red commented Oct 24, 2025

Uh oh!

hi-ogawa commented Oct 24, 2025

Uh oh!

bluwy commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sapphi-red commented Oct 24, 2025

Uh oh!

bluwy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hi-ogawa left a comment •

edited

Loading

bluwy Oct 23, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 23, 2025 •

edited

Loading

hi-ogawa left a comment •

edited

Loading

bluwy commented Oct 24, 2025 •

edited

Loading