Deno runner using Vite Environment API

Last October, we saw the release of Deno 2.0 with very robust npm support, described as “backwards-compatible, forward-thinking.” The following month the Vite team announced Vite 6, “the most significant major release since Vite 2.” Then right as 2024 was drawing to a close, the React team released React 19 as stable.

What a whirlwind way to finish out the year!

I have not been able to follow the JavaScript ecosystem for the last several years, but with the big announcements from the Vite and Deno teams, I figured it was about time to go explore and get my hands dirty. The new Environment API introduced in Vite 6 was a great opportunity for me to try my hand at integrating Deno as a new environment, and full npm support sounded like it would be a good way for me to take a hard route to getting everything working. While I do not plan on doing anything special with React 19, maybe I will try my hand at using the new prerender APIs at some point down the road.

So here goes my journey, attempting to create a simple Server-Side Rendered React app, using Vite and Deno, complete with the hot-reloading development experience we all enjoy.

Vite overview

#

My impression of Vite from a few years ago was that it had a very seamless experience between development and production. A simple vite dev during development would magically make HMR work, and I could build for production with just vite build. As a developer, I never bothered to look much deeper, but this time around we will be taking a peek under the hood, and see how all the parts come together.

First let’s understand how Vite gives as the development hot reloading experience. There are great articles out there that describe how it uses a combination of esbuild and rollup to enable this, so today, we will focus on the mechanisms that serve the transpiled JavaScript.

Vite has the ability to run in a variety of configurations. The vite setup catalogue has a good overview of the various permutations, but we will pick a few that are the most relevant to us here.

Basic mode

#

This is what you would get if you called vite dev from the typical starter template.

Middleware mode

#

In middleware mode you can run your own customer server using express or similar, and call into Vite APIs to transform index.html or get the bundled JavaScript modules:

Runner mode

#

I just made up this mode, but we will be running a custom server in our desired runtime Deno, that will serve all the assets necessary for the development experience, and also proxy the HMR WebSocket through. This last point is not really necessary, but I found it informative to see the messages being sent to the browser by the Vite server.

Unlike the Middleware mode above, the customer server and Vite server run in different processes, in different JavaScript runtimes, so they will need to communicate over a network socket. Let’s dig into this link.

Vite (classic) SSR

#

Before we get into the Environment API, let’s take a look at how SSR used to work. The Vite SSR page shows how you might implement SSR using express and Vite in middleware mode. The following code is lifted straight from the documentation, and describes the steps involved in completing an HTTP request.

// From: https://vite.dev/guide/ssr
app.use('*', async (req, res, next) => {
  const url = req.originalUrl

  try {
    // 1. Read index.html
    let template = fs.readFileSync(
      path.resolve(__dirname, 'index.html'),
      'utf-8',
    )

    // 2. Apply Vite HTML transforms. This injects the Vite HMR client,
    //    and also applies HTML transforms from Vite plugins, e.g. global
    //    preambles from @vitejs/plugin-react
    template = await vite.transformIndexHtml(url, template)

    // 3. Load the server entry. ssrLoadModule automatically transforms
    //    ESM source code to be usable in Node.js! There is no bundling
    //    required, and provides efficient invalidation similar to HMR.
    const { render } = await vite.ssrLoadModule('/src/entry-server.js')

    // 4. render the app HTML. This assumes entry-server.js's exported
    //     `render` function calls appropriate framework SSR APIs,
    //    e.g. ReactDOMServer.renderToString()
    const appHtml = await render(url)

    // 5. Inject the app-rendered HTML into the template.
    const html = template.replace(`<!--ssr-outlet-->`, () => appHtml)

    // 6. Send the rendered HTML back.
    res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
  } catch (e) {
    // If an error is caught, let Vite fix the stack trace so it maps back
    // to your actual source code.
    vite.ssrFixStacktrace(e)
    next(e)
  }
})

Notice that in the example above, Vite loads /src/entry-server.js as the SSR entry point. This is the function that will generate the HTML fragments to be injected into the index.html template using a string replace.

Pretty straight forward. For those who don’t like the clunkiness of string replacing HTML fragments, you can describe the entire HTML template as JSX as described in the React documentation

This was easy, because both the express server and the Vite server run inside of a Node runtime. From inside the express handler, we are directly calling into Vite’s APIs such as transformIndexHtml and ssrLoadModule. When we move to the Environment API using Deno as our custom server, these Vite APIs will not be available to us. We will have to implement some RPC (remote procedure call) mechanism to accomplish this. The Vite Environment API provides us with various building blocks to ease this process.

Vite Environment API

#

ModuleRunnerTransport

#

The new Environment API defines a ModuleRunnerTransport, copied below, so that we can choose how to communicate between the custom Deno server, and the Vite server. I assume most of us will use HTTP or WebSockets, but it could be anything, as long as we expose a transport implementation as follows:

interface ModuleRunnerTransport {
  connect?(handlers: ModuleRunnerTransportHandlers): Promise<void> | void
  disconnect?(): Promise<void> | void
  send?(data: HotPayload): Promise<void> | void
  invoke?(data: HotPayload): Promise<{ result: any } | { error: any }>
  timeout?: number
}

Note the following from the documentation:

When `invoke` method is not implemented, the `send` method and `connect` method is required to be implemented. Vite will construct the `invoke` internally.

The idea is that if you have a bidirectional link such as WebSocket, you would implement send and connect, but you can choose to just implement an invoke endpoint in your Vite server, that gets called by your custom server. In this case, you will not get “push notifications” if you will, when the source code gets updated.

While these are just generic transport methods, we will see that the Vite development server already implements the invoke function on the development server side. However, we will still need to implement transformIndexHtml on our own. We will get to those later.

ModuleRunner

#

Since we are trying to create a SSR app, so we need to be able to execute a renderToString inside of the Deno runtime. Luckily the Vite team has provided us with ModuleRunner which can be imported via vite/module-runner, which contains just the bare minimum to provide the module runner. It does not have any of the heavy duty Vite machinery, and does not have any dependencies on Node APIs. Our custom Deno dev server will use the module runner package to evaluate the code it receives from the Vite server.

We still need to implement our own ModuleRunnerTransport, as the Vite APIs make no assumptions about the link between the custom Deno dev server, and the Vite server. We will make a quick wrapper around a WebSocket for this:

const transport: ModuleRunnerTransport = {
  connect: ({ onMessage, onDisconnection }) => {
    onMessageHandler = (evt: MessageEvent) => {
      onMessage(JSON.parse(evt.data))
    }
    onDisconnectHandler = () => {
      onDisconnection()
    }
    this.socket.addEventListener("message", onMessageHandler)
    this.socket.addEventListener("close", onDisconnectHandler)
  },
  send: (data) => {
    this.socket.send(JSON.stringify(data))
  },
  disconnect: () => {
    if (onMessageHandler) {
      this.socket.removeEventListener("message", onMessageHandler)
      this.socket.removeEventListener("close", onDisconnectHandler)
    }
  },
}

The Vite-provided ModuleRunner will call invoke on the provided ModuleRunnerTransport interface.

As the web developer, all we have to do is initialize the ModuleRunner, and import the module. This is really cool, you’re importing a JavaScript module in Deno, not from the file system, but over the network!

export const ImportModuleForUrl = (url: string) => {  
  const runner = new ModuleRunner(
    {
      root: root,
      transport,
      hmr: false,
    },
    new ESModulesEvaluator(),
    console.log,
  )
  return (await runner.import(url))
}

Implementing transformIndexHtml

#

Vite plugin implementation

#

In reality it pretty much comes down to filling in the script tag with the correct path to JavaScript. We want to have Vite handle this for us. Since we need access to the transport, we will just shoehorn it in the createEnvironment function

dev: {
  createEnvironment: (name, config) => {
    const transport = new DenoHotChannel(pluginState)
    transport.on("deno-ssr:transformIndexHtml", async (parsed, client) => {
      if (!pluginState.devServer) {
        return
      }
      const __dirname = path.dirname(fileURLToPath(import.meta.url))
      const indexHtmlPath = path.resolve(__dirname, "../index.html")
      const template = fs.readFileSync(indexHtmlPath, "utf-8")
      const transformed = await pluginState.devServer.transformIndexHtml(
        parsed.url,
        template,
      )
      client.send({
        type: "custom",
        event: "deno-ssr:transformIndexHtml",
        data: transformed,
      })
    })
    return createDenoDevEnvironment(name, config, {
      hot: true,
      transport: transport,
    })
  },
},

Deno (runner) implementation

#

We will piggy back on the existing WebSocket we created for the ModuleRunnerTransport. This function implementation will be called directly from the main server request handler, in much the same way that the classic Vite SSR implementation using middleware calls vite.transformIndexHtml.

transformIndexHtml(url: string): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    this.conn.socket.addEventListener("message", (evt) => {
      const parsed: HotPayload = JSON.parse(evt.data)
      if (parsed.type !== "custom") {
        return
      }
      if (parsed.event !== EventNameTransformIndexHtml) {
        return
      }
      resolve(parsed.data)
    })
    const request: HotPayload = {
      type: "custom",
      event: EventNameTransformIndexHtml,
      data: { url },
    }
    this.conn.socket.send(JSON.stringify(request))
  })
}

The end result

#