Stabilizing ViteRuntime

[sheremet-va]

ViteRuntime

• Introduced in 5.1
• Rational in Original PR
• Docs
• Example usages: https://github.com/sapphi-red/vite-envs/tree/use-vite-runtime
• Should be used by framework authors instead of ssrLoadModule

We are gathering feedback to see if the feature should be moved out of experimental in Vite 6. If you have any feedback, please let's discuss it here.

[nitedani]

I'm trying to replace ssrLoadModule with the new features, in an SSR app.
I would like to run some cleanup code after the "server" files are changed, but before executeUrl is called or the "full-reload" message is sent to the client.

With ssrLoadModule, I achieve this by manually tracking the dependencies of the server entry, and use handleHotUpdate to check whether it was a "server" update or a "client" update. If it was a server update, I await the cleanup function, call ssrLoadModule again, then send the "full-reload" event to the client.
https://github.com/nitedani/vite5.1-experiment/blob/main/start-old.js

I couldn't achieve the same behavior with the new features.
I would need two things when a server reload is executed:

• a way to run my cleanup code before executeUrl
• the "full-reload" event to be only sent after executeUrl resolved
  https://github.com/nitedani/vite5.1-experiment/blob/main/start-new.js

[sheremet-va]

it re-executes the entry on "full-reload". This doesn't make sense to me, because a "full-reload" doesn't translate to changes in the server runtime module graph.

This is a shortcoming of the current HMR API - it shares the graph with SSR and browser modules. There is a proposal to split modules graph for different runtimes.

This is so I can manually restart the worker process/thread, then send "full-reload" to the client after the entry is loaded

There is an example in the original PR on how to do it (just define your own handler in connector's onUpdate):

export class WorkerPortHMRConnector implements HMRConnection {
  constructor(private readonly port: MessagePort) {}

  send(message: string): void {
    this.port.postMessage({ type: 'hmr:custom', payload: message })
  }

  onUpdate(handler: (payload: HMRPayload) => void): () => void {
    function onMessage({
      type,
      payload,
    }: {
      type: string
      payload: HMRPayload
    }) {
      if (type === 'vite:hmr') {
        if(payload.type === 'full-reload') {
          rpc('reload')
        } else {
          handler(payload)
        }
      }
    }

    this.port.on('message', onMessage)
  }
}

function createWorkerViteRuntime(
  root: string,
  rpc: WorkerExampleRPC,
): Promise<ViteRuntime> {
  const hmrConnector = new WorkerPortHMRConnector(options.port)
  return new ViteRuntime(
    {
      root: options.root,
      fetchModule: (id) => rpc('fetchModule', { id }),
      hmr: hmrConnector,
    },
    new ESModulesRunner(),
  )
}

[nitedani]

I've seen the commit 57463fc#diff-9148072a8dc798e63867023b8091afdea1d41df0b8c872a0adbc860cc4555795L55
It looks good 👍

There is an other issue:
The hmr channels work in parallel. So on a "full-reload" the browser immediately reloads, not waiting for executeUrl to resolve in the runtime. I'd like to send "full-reload" to the browser only after executeUrl is resolved.

[sheremet-va]

Hm, I am not sure that we can make them sequential. Currently, you do this via handleHotUpdate, right?

Maybe we can add an order property to HMR channels 🤷🏻 I don't know what is the best course of action here, to be honest.

[patak-dev]

I think we may be able to do this as part of #16003. In the proof of concept, I'm deprecating handleHotUpdate because it will continue to return a list of mixed client/ssr Module Nodes (proxies to the real separate graphs for backward compat). We would need to add a new hook, called hotUpdate for now. This one will give you the runtime and module nodes for that runtime. We can call hotUpdate for every runtime in parallel, but we could also decide to call it for each runtime in series.

PS: renaming handleHotUpdate is also not bad also because the handle part is implicit, that is how hooks work, and also handleHotUpdate: { handle: ... } looks weird.

[nitedani]

Runtime separated hotUpdate + sequential sounds good, it would work for me.

[nlwillia]

One thing I noticed for HMR is that (non statically analyzable) dynamic imports don’t participate in the module graph. You can ignore the warning and dynamic import anyway, but a change to that file is going to be a full-reload. I imagine this would be inconvenient to handle, and it’s an issue for build, but vite for non-built HMR use cases is kind of a new scenario where this may be worth considering down the road.

[mayank99]

Am I understanding correctly that this new API can only execute entire files? Rather than specific parts of the same file?

I understand it's probably 10x simpler to implement this way in Vite, but the closure extraction pattern provides clear DX benefits (see Remix loaders/actions, Qwik $) and currently requires a userland implementation.

[manspaniel]

Looking good! I'm noticing a difference in how virtual entry files are handled between ssrLoadModule and executeEntrypoint.

With ssrLoadModule, I can use my virtual module's file path, ie. vite.ssrLoadModule(join(rootDir, "_ssr.js"))

But if I try that with runtime.executeEntrypoint, an error is thrown stating that the module doesn't exist. Using the return value of resolveId from my plugin does work, though: runtime.executeEntrypoint("\0virtual:eddev-ssr")

Not sure if this is intentional, a bug or misconfiguration on my part — but just thought I'd flag!

[sheremet-va]

This looks like a bug, they should behave the same way.

[alexanderniebuhr]

I try to follow the examples, and get this integrated for the Astro Cloudflare adapter 🚀
It looks very promising and it might already be exactly what we are looking for, however looking at the example implementation I see vite.ssr.runtime: https://github.com/sapphi-red/vite-envs/blob/use-vite-runtime/examples/cloudflare-pages/vite.config.ts#L30

It doesn't look like that config is anywhere found in the docs. Was there a change or are docs missing something?

[sheremet-va]

This is unique to sapphi's implementation and not part of the API: https://github.com/sapphi-red/vite-envs/blob/use-vite-runtime/packages/standalone/src/config.ts

[alexanderniebuhr]

Thanks for pointing this out. Are there any other reference / example implementations for workerd which only use the API?

[sheremet-va]

@hi-ogawa also has some examples: hi-ogawa/vite-plugins#155

[hi-ogawa]

It's still named vite-node-miniflare but now vite-node part is completely replaced with ViteRuntime and the code became simpler overall. Please feel free to take a look https://github.com/hi-ogawa/vite-plugins/tree/main/packages/vite-node-miniflare

[hi-ogawa]

I just got a very minor question about HMRRuntimeConnection https://main.vitejs.dev/guide/api-vite-runtime.html#hmrruntimeconnection. Jsdoc of send says Send message to the client, but I thought this is used to send events from ViteRuntime (client) to Vite dev server, so I felt the comment is a little off. Am I correct?

[sheremet-va]

It's a typo, the usecase fir this method is explained in the next paragraph, it sends data to the server

[IgorMinar]

Hi there 👋🏻 , our team at Cloudflare is excited about the new Vite Runtime APIs. We've extensively experimented with them and have put together feedback that we think might be helpful in evolving the APIs further. Since the focus of our feedback is specifically on supporting alternative JS runtimes in Vite, I created an offshoot discussion so that the feedback is easier to digest and further discuss: #16053

[patak-dev]

We are working on a new proposal that supersedes the released version of Vite Runtime API.

You can check it out in docs form here: Vite Environment API docs.

And we are discussing it here:

• docs: environment API proposal #16089

Looking forward to your feedback, in this discussion or directly in the PR.