Environment Runtimes

Creating custom environment factories and module runners for different runtimes

Release Candidate: The Environment API is generally in the release candidate phase. We’ll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.

Resources:

• Feedback discussion
• Environment API PR

Please share your feedback with us.

Environment Factories

Environment factories are intended to be implemented by Environment providers like Cloudflare, and not by end users. Environment factories return a EnvironmentOptions for the most common case of using the target runtime for both dev and build environments.

The default environment options can also be set so the user doesn’t need to do it.

function createWorkerdEnvironment(
  userConfig: EnvironmentOptions,
): EnvironmentOptions {
  return mergeConfig(
    {
      resolve: {
        conditions: [/*...*/],
      },
      dev: {
        createEnvironment(name, config) {
          return createWorkerdDevEnvironment(name, config, {
            hot: true,
            transport: customHotChannel(),
          })
        },
      },
      build: {
        createEnvironment(name, config) {
          return createWorkerdBuildEnvironment(name, config)
        },
      },
    },
    userConfig,
  )
}

Usage in Config

Then the config file can be written as:

import { createWorkerdEnvironment } from 'vite-environment-workerd'

export default {
  environments: {
    ssr: createWorkerdEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
    rsc: createWorkerdEnvironment({
      build: {
        outDir: '/dist/rsc',
      },
    }),
  },
}

And frameworks can use an environment with the workerd runtime to do SSR using:

const ssrEnvironment = server.environments.ssr

Creating a New Environment Factory

A Vite dev server exposes two environments by default:

• A client environment (browser environment by default)
• An ssr environment (runs in the same Node runtime as the Vite server by default)

The client environment is a browser environment by default, and the module runner is implemented by importing the virtual module /@vite/client to client apps. The SSR environment runs in the same Node runtime as the Vite server by default and allows application servers to be used to render requests during dev with full HMR support.

Module Processing and Execution

The transformed source code is called a module, and the relationships between the modules processed in each environment are kept in a module graph. The transformed code for these modules is sent to the runtimes associated with each environment to be executed.

When a module is evaluated in the runtime, its imported modules will be requested triggering the processing of a section of the module graph.

Module Runners

A Vite Module Runner allows running any code by processing it with Vite plugins first. It is different from server.ssrLoadModule because the runner implementation is decoupled from the server.

This allows library and framework authors to implement their layer of communication between the Vite server and the runner:

• The browser communicates with its corresponding environment using the server WebSocket and through HTTP requests
• The Node Module runner can directly do function calls to process modules as it is running in the same process
• Other environments could run modules connecting to a JS runtime like workerd, or a Worker Thread as Vitest does

Creating Custom Environments

One of the goals of this feature is to provide a customizable API to process and run code. Users can create new environment factories using the exposed primitives.

import { DevEnvironment, HotChannel } from 'vite'

function createWorkerdDevEnvironment(
  name: string,
  config: ResolvedConfig,
  context: DevEnvironmentContext
) {
  const connection = /* ... */
  const transport: HotChannel = {
    on: (listener) => { connection.on('message', listener) },
    send: (data) => connection.send(data),
  }

  const workerdDevEnvironment = new DevEnvironment(name, config, {
    options: {
      resolve: { conditions: ['custom'] },
      ...context.options,
    },
    hot: true,
    transport,
  })
  return workerdDevEnvironment
}

There are multiple communication levels for the DevEnvironment. To make it easier for frameworks to write runtime agnostic code, we recommend to implement the most flexible communication level possible.

ModuleRunner

A module runner is instantiated in the target runtime. All APIs in this section are imported from vite/module-runner unless stated otherwise. This export entry point is kept as lightweight as possible, only exporting the minimal needed to create module runners.

Type Signature

export class ModuleRunner {
  constructor(
    public options: ModuleRunnerOptions,
    public evaluator: ModuleEvaluator = new ESModulesEvaluator(),
    private debug?: ModuleRunnerDebugger,
  ) {}
  
  public async import<T = any>(url: string): Promise<T>
  public clearCache(): void
  public async close(): Promise<void>
  public isClosed(): boolean
}

Constructor

options · ModuleRunnerOptions · required

Configuration options for the module runner

evaluator · ModuleEvaluator · default: "new ESModulesEvaluator()"

Module evaluator responsible for executing the code. Vite exports ESModulesEvaluator which uses new AsyncFunction to evaluate code.

debug · ModuleRunnerDebugger

Debugger instance for debugging module execution

Methods

import · <T = any>(url: string) => Promise<T>

Execute a module by URL. Accepts file path, server path, or id relative to the root.

clearCache · () => void

Clear all caches including HMR listeners

close · () => Promise<void>

Clear all caches, remove all HMR listeners, reset sourcemap support. This method doesn’t stop the HMR connection.

isClosed · () => boolean

Returns true if the runner has been closed by calling close()

Example Usage

import {
  ModuleRunner,
  ESModulesEvaluator,
  createNodeImportMeta,
} from 'vite/module-runner'
import { transport } from './rpc-implementation.js'

const moduleRunner = new ModuleRunner(
  {
    transport,
    createImportMeta: createNodeImportMeta, // if the module runner runs in Node.js
  },
  new ESModulesEvaluator(),
)

await moduleRunner.import('/src/entry-point.js')

The module evaluator in ModuleRunner is responsible for executing the code. You can provide your own implementation if your JavaScript runtime doesn’t support unsafe evaluation.

When Vite server triggers full-reload HMR event, all affected modules will be re-executed. Be aware that Module Runner doesn’t update exports object when this happens (it overrides it), you would need to run import or get the module from evaluatedModules again if you rely on having the latest exports object.

ModuleRunnerOptions

interface ModuleRunnerOptions {
  transport: ModuleRunnerTransport
  sourcemapInterceptor?:
    | false
    | 'node'
    | 'prepareStackTrace'
    | InterceptorOptions
  hmr?: boolean | ModuleRunnerHmr
  evaluatedModules?: EvaluatedModules
}

Properties

transport · ModuleRunnerTransport · required

A set of methods to communicate with the server

sourcemapInterceptor · false | 'node' | 'prepareStackTrace' | InterceptorOptions

Configure how source maps are resolved. Prefers node if process.setSourceMapsEnabled is available. Otherwise it will use prepareStackTrace by default which overrides Error.prepareStackTrace method. You can provide an object to configure how file contents and source maps are resolved for files that were not processed by Vite.

hmr · boolean | ModuleRunnerHmr · default: "true"

Disable HMR or configure HMR options

evaluatedModules · EvaluatedModules

Custom module cache. If not provided, it creates a separate module cache for each module runner instance.

ModuleEvaluator

The module evaluator interface for executing transformed code.

interface ModuleEvaluator {
  startOffset?: number
  
  runInlinedModule(
    context: ModuleRunnerContext,
    code: string,
    id: string,
  ): Promise<any>
  
  runExternalModule(file: string): Promise<any>
}

Properties

startOffset · number

Number of prefixed lines in the transformed code

Methods

runInlinedModule · (context: ModuleRunnerContext, code: string, id: string) => Promise<any> · required

Evaluate code that was transformed by Vite

• context: Function context
• code: Transformed code
• id: ID that was used to fetch the module

runExternalModule · (file: string) => Promise<any> · required

Evaluate externalized module

• file: File URL to the external module

Vite exports ESModulesEvaluator that implements this interface by default. It uses new AsyncFunction to evaluate code, so if the code has inlined source map it should contain an offset of 2 lines to accommodate for new lines added.

This is done automatically by the ESModulesEvaluator. Custom evaluators will not add additional lines.

ModuleRunnerTransport

Transport object that communicates with the environment via an RPC or by directly calling the function.

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
}

Properties and Methods

connect · (handlers: ModuleRunnerTransportHandlers) => Promise<void> | void

Connect to the environment and register message handlers

disconnect · () => Promise<void> | void

Disconnect from the environment

send · (data: HotPayload) => Promise<void> | void

Send data to the environment (required if invoke is not implemented)

invoke · (data: HotPayload) => Promise<{ result: any } | { error: any }>

Invoke a method on the environment and get the result. If not implemented, Vite will construct it internally using send and connect.

timeout · number

Timeout in milliseconds for invoke calls

Worker Thread Example

You need to couple the transport with the HotChannel instance on the server. Here’s an example where module runner is created in the worker thread:

worker.js

import { parentPort } from 'node:worker_threads'
import { fileURLToPath } from 'node:url'
import {
  ESModulesEvaluator,
  ModuleRunner,
  createNodeImportMeta,
} from 'vite/module-runner'

/** @type {import('vite/module-runner').ModuleRunnerTransport} */
const transport = {
  connect({ onMessage, onDisconnection }) {
    parentPort.on('message', onMessage)
    parentPort.on('close', onDisconnection)
  },
  send(data) {
    parentPort.postMessage(data)
  },
}

const runner = new ModuleRunner(
  {
    transport,
    createImportMeta: createNodeImportMeta,
  },
  new ESModulesEvaluator(),
)

Make sure to implement the vite:client:connect / vite:client:disconnect events in the on / off methods when those methods exist. vite:client:connect event should be emitted when the connection is established, and vite:client:disconnect event should be emitted when the connection is closed. The HotChannelClient object passed to the event handler must have the same reference for the same connection.

HTTP Request Example

A different example using an HTTP request to communicate between the runner and the server:

import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'

export const runner = new ModuleRunner(
  {
    transport: {
      async invoke(data) {
        const response = await fetch(`http://my-vite-server/invoke`, {
          method: 'POST',
          body: JSON.stringify(data),
        })
        return response.json()
      },
    },
    hmr: false, // disable HMR as HMR requires transport.connect
  },
  new ESModulesEvaluator(),
)

await runner.import('/entry.js')

In this case, the handleInvoke method in the NormalizedHotChannel can be used:

const customEnvironment = new DevEnvironment(name, config, context)

server.onRequest((request: Request) => {
  const url = new URL(request.url)
  if (url.pathname === '/invoke') {
    const payload = (await request.json()) as HotPayload
    const result = customEnvironment.hot.handleInvoke(payload)
    return new Response(JSON.stringify(result))
  }
  return Response.error()
})

For HMR support, send and connect methods are required. The send method is usually called when the custom event is triggered (like, import.meta.hot.send("my-event")).

Vite exports createServerHotChannel from the main entry point to support HMR during Vite SSR.