Environment Instances

Using Environment instances in Vite’s dev server and programmatic API

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.

Accessing the Environments

During dev, the available environments in a dev server can be accessed using server.environments:

// create the server, or get it from the configureServer hook
const server = await createServer(/* options */)

const clientEnvironment = server.environments.client
clientEnvironment.transformRequest(url)
console.log(server.environments.ssr.moduleGraph)

You can also access the current environment from plugins. See the Environment API for Plugins for more details.

DevEnvironment Class

During dev, each environment is an instance of the DevEnvironment class:

class DevEnvironment {
  name: string
  hot: NormalizedHotChannel
  moduleGraph: EnvironmentModuleGraph
  plugins: Plugin[]
  pluginContainer: EnvironmentPluginContainer
  config: ResolvedConfig & ResolvedDevEnvironmentOptions

  constructor(
    name: string,
    config: ResolvedConfig,
    context: DevEnvironmentContext,
  )

  async transformRequest(url: string): Promise<TransformResult | null>
  async warmupRequest(url: string): Promise<void>
}

Properties

name · string

Unique identifier for the environment in a Vite server. By default Vite exposes ‘client’ and ‘ssr’ environments.

hot · NormalizedHotChannel

Communication channel to send and receive messages from the associated module runner in the target runtime

moduleGraph · EnvironmentModuleGraph

Graph of module nodes, with the imported relationship between processed modules and the cached result of the processed code

plugins · Plugin[]

Resolved plugins for this environment, including the ones created using the per-environment create hook

pluginContainer · EnvironmentPluginContainer

Allows to resolve, load, and transform code through the environment plugins pipeline

config · ResolvedConfig & ResolvedDevEnvironmentOptions

Resolved config options for this environment. Options at the server global scope are taken as defaults for all environments, and can be overridden (resolve conditions, external, optimizedDeps)

Constructor

name · string · required

Environment name

config · ResolvedConfig · required

Resolved Vite configuration

context · DevEnvironmentContext · required

Environment context with HMR settings and options

Show DevEnvironmentContext Interface

interface DevEnvironmentContext {
  hot: boolean
  transport?: HotChannel | WebSocketServer
  options?: EnvironmentOptions
  remoteRunner?: {
    inlineSourceMap?: boolean
  }
  depsOptimizer?: DepsOptimizer
}

Methods

transformRequest()

Resolve the URL to an id, load it, and process the code using the plugins pipeline. The module graph is also updated.

Type Signature:

async transformRequest(url: string): Promise<TransformResult | null>

url · string · required

The URL to transform

Returns:

result · TransformResult | null

The transform result or null if the module couldn’t be processed

Show TransformResult Interface

interface TransformResult {
  code: string
  map: SourceMap | { mappings: '' } | null
  etag?: string
  deps?: string[]
  dynamicDeps?: string[]
}

An environment instance in the Vite server lets you process a URL using the environment.transformRequest(url) method. This function will use the plugin pipeline to resolve the url to a module id, load it (reading the file from the file system or through a plugin that implements a virtual module), and then transform the code.

While transforming the module, imports and other metadata will be recorded in the environment module graph by creating or updating the corresponding module node. When processing is done, the transform result is also stored in the module.

warmupRequest()

Register a request to be processed with low priority. This is useful to avoid waterfalls.

Type Signature:

async warmupRequest(url: string): Promise<void>

url · string · required

The URL to warmup

The Vite server has information about the imported modules by other requests, so it can warmup the module graph so the modules are already processed when they are requested.

Separate Module Graphs

Each environment has an isolated module graph. All module graphs have the same signature, so generic algorithms can be implemented to crawl or query the graph without depending on the environment.

hotUpdate is a good example. When a file is modified, the module graph of each environment will be used to discover the affected modules and perform HMR for each environment independently.

Vite v5 had a mixed Client and SSR module graph. Given an unprocessed or invalidated node, it isn’t possible to know if it corresponds to the Client, SSR, or both environments. Module nodes have some properties prefixed, like clientImportedModules and ssrImportedModules (and importedModules that returns the union of both).

importers contains all importers from both the Client and SSR environment for each module node. A module node also has transformResult and ssrTransformResult. A backward compatibility layer allows the ecosystem to migrate from the deprecated server.moduleGraph.

EnvironmentModuleNode

Each module is represented by an EnvironmentModuleNode instance. Modules may be registered in the graph without yet being processed (transformResult would be null in that case). importers and importedModules are also updated after the module is processed.

class EnvironmentModuleNode {
  environment: string
  url: string
  id: string | null = null
  file: string | null = null
  type: 'js' | 'css'
  
  importers = new Set<EnvironmentModuleNode>()
  importedModules = new Set<EnvironmentModuleNode>()
  importedBindings: Map<string, Set<string>> | null = null
  
  info?: ModuleInfo
  meta?: Record<string, any>
  transformResult: TransformResult | null = null
  
  acceptedHmrDeps = new Set<EnvironmentModuleNode>()
  acceptedHmrExports: Set<string> | null = null
  isSelfAccepting?: boolean
  lastHMRTimestamp = 0
  lastInvalidationTimestamp = 0
}

Properties

environment · string

The environment this module belongs to

url · string

The module URL

id · string | null

The resolved module ID (null if not yet resolved)

file · string | null

The file path on disk (null for virtual modules)

type · 'js' | 'css'

Module type

importers · Set<EnvironmentModuleNode>

Modules that import this module

importedModules · Set<EnvironmentModuleNode>

Modules imported by this module

transformResult · TransformResult | null

The cached transform result (null if not yet processed)

isSelfAccepting · boolean | undefined

Whether this module accepts HMR updates for itself

EnvironmentModuleGraph

environment.moduleGraph is an instance of EnvironmentModuleGraph:

class EnvironmentModuleGraph {
  environment: string
  
  urlToModuleMap = new Map<string, EnvironmentModuleNode>()
  idToModuleMap = new Map<string, EnvironmentModuleNode>()
  etagToModuleMap = new Map<string, EnvironmentModuleNode>()
  fileToModulesMap = new Map<string, Set<EnvironmentModuleNode>>()

  constructor(
    environment: string,
    resolveId: (url: string) => Promise<PartialResolvedId | null>,
  )

  async getModuleByUrl(rawUrl: string): Promise<EnvironmentModuleNode | undefined>
  getModuleById(id: string): EnvironmentModuleNode | undefined
  getModulesByFile(file: string): Set<EnvironmentModuleNode> | undefined
  
  onFileChange(file: string): void
  onFileDelete(file: string): void
  
  invalidateModule(
    mod: EnvironmentModuleNode,
    seen?: Set<EnvironmentModuleNode>,
    timestamp?: number,
    isHmr?: boolean,
  ): void
  
  invalidateAll(): void
  
  async ensureEntryFromUrl(
    rawUrl: string,
    setIsSelfAccepting?: boolean,
  ): Promise<EnvironmentModuleNode>
  
  createFileOnlyEntry(file: string): EnvironmentModuleNode
  async resolveUrl(url: string): Promise<ResolvedUrl>
  
  updateModuleTransformResult(
    mod: EnvironmentModuleNode,
    result: TransformResult | null,
  ): void
  
  getModuleByEtag(etag: string): EnvironmentModuleNode | undefined
}

Properties

environment · string

The environment name this graph belongs to

urlToModuleMap · Map<string, EnvironmentModuleNode>

Map from module URL to module node

idToModuleMap · Map<string, EnvironmentModuleNode>

Map from module ID to module node

fileToModulesMap · Map<string, Set<EnvironmentModuleNode>>

Map from file path to set of module nodes (one file can have multiple modules)

Methods

getModuleByUrl · (rawUrl: string) => Promise<EnvironmentModuleNode | undefined>

Get a module by its URL

getModuleById · (id: string) => EnvironmentModuleNode | undefined

Get a module by its resolved ID

getModulesByFile · (file: string) => Set<EnvironmentModuleNode> | undefined

Get all modules associated with a file path

onFileChange · (file: string) => void

Handle file change events

onFileDelete · (file: string) => void

Handle file deletion events

invalidateModule · (mod: EnvironmentModuleNode, seen?: Set, timestamp?: number, isHmr?: boolean) => void

Invalidate a module and optionally its importers

invalidateAll · () => void

Invalidate all modules in the graph

ensureEntryFromUrl · (rawUrl: string, setIsSelfAccepting?: boolean) => Promise<EnvironmentModuleNode>

Ensure a module entry exists for the given URL, creating it if necessary

updateModuleTransformResult · (mod: EnvironmentModuleNode, result: TransformResult | null) => void

Update the transform result for a module