ModuleRunner Deep Dive

// Conceptual illustration (refer to official docs for the exact API)
const runner = new ModuleRunner(ssrEnvironment)

// Execute a module inside the ssr environment
const { render } = await runner.import("/src/entry-server.tsx")
const html = await render("/page")

runner.import("/src/App.tsx")
         │
         ▼
1. Check the module cache
   ├── Hit and not invalidated → return the cached module exports directly
   └── Miss / invalidated → continue →

2. Request a module transform from DevEnvironment
   ├── resolve → load → transform pipeline executes
   └── Returns the compiled JS code

3. Execute the code inside the runner's current execution context
   ├── Similar to new Function(code)()
   └── But with full import/export support

4. Collect exports, add to cache

5. Return the module exports object

File changed: /src/utils.ts
         │
         ▼
DevEnvironment receives the watcher event
         │
         ▼
Notifies the runner via HotChannel: utils.ts is invalidated
         │
         ▼
runner.moduleCache.invalidate("/src/utils.ts")
         │
         ▼
Next runner.import("/src/utils.ts") re-executes

// server.js (conceptual illustration)
import { createServer } from "vite"

const vite = await createServer({
  server: { middlewareMode: true },
})

// Get the ModuleRunner for the ssr environment
// Refer to official docs for the exact API
const runner = getModuleRunner(vite.environments.ssr)

app.use(async (req, res) => {
  try {
    // Each request uses runner.import to get the latest module
    // If the file hasn't changed, the cache is hit — nearly zero overhead
    const { render } = await runner.import("/src/entry-server.tsx")
    const html = await render(req.url)

    res.setHeader("Content-Type", "text/html")
    res.end(html)
  } catch (e) {
    vite.ssrFixStacktrace(e)
    res.status(500).end(String(e))
  }
})

// Execute multiple modules at once
const results = await Promise.all([
  runner.import("/src/routes/home.tsx"),
  runner.import("/src/routes/about.tsx"),
  runner.import("/src/routes/404.tsx"),
])

// The runner should be closed alongside the server's lifecycle
process.on("SIGTERM", async () => {
  await runner.close() // clean up resources
  await vite.close()
})

// Code executing inside the runner:
import { readFile } from "node:fs/promises" // Node.js API

// Global objects are Node.js globals
console.log(typeof window) // "undefined" (if running in Node)
console.log(typeof process) // "object"

// But if the runner is running in an Edge Runtime:
// console.log(typeof window)  // "object" (Edge has window-like objects)
// console.log(typeof process)  // "undefined"

// Implement a simple SSR rendering server:
// 1. Create a Vite dev server
// 2. Get the ModuleRunner for the ssr environment
// 3. For each HTTP request:
//    a. Use runner.import to get the entry-server module
//    b. Call render(url) to get the HTML
//    c. Return the complete HTML

import { createServer } from "node:http"
import { createServer as createViteServer } from "vite"

async function main() {
  const vite = await createViteServer({
    server: { middlewareMode: true },
    appType: "custom",
    environments: {
      ssr: {
        resolve: {
          conditions: ["node", "import"],
        },
      },
    },
  })

  // TODO:
  // 1. Get the runner for the ssr environment (use official API)
  // 2. Create an HTTP server
  // 3. In the request handler, use runner.import to execute entry-server

  const server = createServer(async (req, res) => {
    // TODO
  })

  server.listen(3000)
  console.log("SSR server: http://localhost:3000")
}

main()