feat(ssr): support import.meta.resolve in module runner (#20260)

sapphi-red · web-flow · commit 62835f7c06d3 · 2025-07-28T12:14:33.000+09:00
diff --git a/docs/guide/api-environment-runtimes.md b/docs/guide/api-environment-runtimes.md
@@ -153,12 +153,17 @@ Module runner exposes `import` method. When Vite server triggers `full-reload` H
 **Example Usage:**
 
 ```js
-import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'
+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(),
 )
@@ -278,7 +283,11 @@ You need to couple it with the `HotChannel` instance on the server like in this
 ```js [worker.js]
 import { parentPort } from 'node:worker_threads'
 import { fileURLToPath } from 'node:url'
-import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'
+import {
+  ESModulesEvaluator,
+  ModuleRunner,
+  createNodeImportMeta,
+} from 'vite/module-runner'
 
 /** @type {import('vite/module-runner').ModuleRunnerTransport} */
 const transport = {
@@ -294,6 +303,7 @@ const transport = {
 const runner = new ModuleRunner(
   {
     transport,
+    createImportMeta: createNodeImportMeta,
   },
   new ESModulesEvaluator(),
 )
diff --git a/packages/vite/src/module-runner/createImportMeta.ts b/packages/vite/src/module-runner/createImportMeta.ts
@@ -0,0 +1,62 @@
+import { isWindows } from '../shared/utils'
+import {
+  type ImportMetaResolver,
+  createImportMetaResolver,
+} from './importMetaResolver'
+import type { ModuleRunnerImportMeta } from './types'
+import { posixDirname, posixPathToFileHref, toWindowsPath } from './utils'
+
+const envProxy = new Proxy({} as any, {
+  get(_, p) {
+    throw new Error(
+      `[module runner] Dynamic access of "import.meta.env" is not supported. Please, use "import.meta.env.${String(p)}" instead.`,
+    )
+  },
+})
+
+export function createDefaultImportMeta(
+  modulePath: string,
+): ModuleRunnerImportMeta {
+  const href = posixPathToFileHref(modulePath)
+  const filename = modulePath
+  const dirname = posixDirname(modulePath)
+  return {
+    filename: isWindows ? toWindowsPath(filename) : filename,
+    dirname: isWindows ? toWindowsPath(dirname) : dirname,
+    url: href,
+    env: envProxy,
+    resolve(_id: string, _parent?: string) {
+      throw new Error('[module runner] "import.meta.resolve" is not supported.')
+    },
+    // should be replaced during transformation
+    glob() {
+      throw new Error(
+        `[module runner] "import.meta.glob" is statically replaced during ` +
+          `file transformation. Make sure to reference it by the full name.`,
+      )
+    },
+  }
+}
+
+let importMetaResolverCache: Promise<ImportMetaResolver | undefined> | undefined
+
+/**
+ * Create import.meta object for Node.js.
+ */
+export async function createNodeImportMeta(
+  modulePath: string,
+): Promise<ModuleRunnerImportMeta> {
+  const defaultMeta = createDefaultImportMeta(modulePath)
+  const href = defaultMeta.url
+
+  importMetaResolverCache ??= createImportMetaResolver()
+  const importMetaResolver = await importMetaResolverCache
+
+  return {
+    ...defaultMeta,
+    resolve(id: string, parent?: string) {
+      const resolver = importMetaResolver ?? defaultMeta.resolve
+      return resolver(id, parent ?? href)
+    },
+  }
+}
diff --git a/packages/vite/src/module-runner/importMetaResolver.ts b/packages/vite/src/module-runner/importMetaResolver.ts
@@ -0,0 +1,48 @@
+export type ImportMetaResolver = (specifier: string, importer: string) => string
+
+const customizationHookNamespace = 'vite-module-runner:import-meta-resolve/v1/'
+const customizationHooksModule = /* js */ `
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(${JSON.stringify(customizationHookNamespace)})) {
+    const data = specifier.slice(${JSON.stringify(customizationHookNamespace)}.length)
+    const [parsedSpecifier, parsedImporter] = JSON.parse(data)
+    specifier = parsedSpecifier
+    context.parentURL = parsedImporter
+  }
+
+  return nextResolve(specifier, context)
+}
+
+`
+
+export async function createImportMetaResolver(): Promise<
+  ImportMetaResolver | undefined
+> {
+  let module: typeof import('node:module')
+  try {
+    module = (await import('node:module')).Module
+  } catch {
+    return
+  }
+  // `module.Module` may be `undefined` when `node:module` is mocked
+  if (!module?.register) {
+    return
+  }
+
+  try {
+    const hookModuleContent = `data:text/javascript,${encodeURI(customizationHooksModule)}`
+    module.register(hookModuleContent)
+  } catch (e) {
+    // For `--experimental-network-imports` flag that exists in Node before v22
+    if ('code' in e && e.code === 'ERR_NETWORK_IMPORT_DISALLOWED') {
+      return
+    }
+    throw e
+  }
+
+  return (specifier: string, importer: string) =>
+    import.meta.resolve(
+      `${customizationHookNamespace}${JSON.stringify([specifier, importer])}`,
+    )
+}
diff --git a/packages/vite/src/module-runner/index.ts b/packages/vite/src/module-runner/index.ts
@@ -7,6 +7,10 @@ export {
 } from './evaluatedModules'
 export { ModuleRunner } from './runner'
 export { ESModulesEvaluator } from './esmEvaluator'
+export {
+  createDefaultImportMeta,
+  createNodeImportMeta,
+} from './createImportMeta'
 
 export { createWebSocketModuleRunnerTransport } from '../shared/moduleRunnerTransport'
 
diff --git a/packages/vite/src/module-runner/runner.ts b/packages/vite/src/module-runner/runner.ts
@@ -1,6 +1,6 @@
 import type { ViteHotContext } from 'types/hot'
 import { HMRClient, HMRContext, type HMRLogger } from '../shared/hmr'
-import { cleanUrl, isPrimitive, isWindows } from '../shared/utils'
+import { cleanUrl, isPrimitive } from '../shared/utils'
 import { analyzeImportedModDifference } from '../shared/ssrTransform'
 import {
   type NormalizedModuleRunnerTransport,
@@ -11,17 +11,11 @@ import { EvaluatedModules } from './evaluatedModules'
 import type {
   ModuleEvaluator,
   ModuleRunnerContext,
-  ModuleRunnerImportMeta,
   ModuleRunnerOptions,
   ResolvedResult,
   SSRImportMetadata,
 } from './types'
-import {
-  posixDirname,
-  posixPathToFileHref,
-  posixResolve,
-  toWindowsPath,
-} from './utils'
+import { posixDirname, posixPathToFileHref, posixResolve } from './utils'
 import {
   ssrDynamicImportKey,
   ssrExportAllKey,
@@ -34,6 +28,7 @@ import { hmrLogger, silentConsole } from './hmrLogger'
 import { createHMRHandlerForRunner } from './hmrHandler'
 import { enableSourceMapSupport } from './sourcemap/index'
 import { ESModulesEvaluator } from './esmEvaluator'
+import { createDefaultImportMeta } from './createImportMeta'
 
 interface ModuleRunnerDebugger {
   (formatter: unknown, ...args: unknown[]): void
@@ -43,13 +38,6 @@ export class ModuleRunner {
   public evaluatedModules: EvaluatedModules
   public hmrClient?: HMRClient
 
-  private readonly envProxy = new Proxy({} as any, {
-    get(_, p) {
-      throw new Error(
-        `[module runner] Dynamic access of "import.meta.env" is not supported. Please, use "import.meta.env.${String(p)}" instead.`,
-      )
-    },
-  })
   private readonly transport: NormalizedModuleRunnerTransport
   private readonly resetSourceMapSupport?: () => void
   private readonly concurrentModuleNodePromises = new Map<
@@ -351,29 +339,13 @@ export class ModuleRunner {
       )
     }
 
+    const createImportMeta =
+      this.options.createImportMeta ?? createDefaultImportMeta
+
     const modulePath = cleanUrl(file || moduleId)
     // disambiguate the `<UNIT>:/` on windows: see nodejs/node#31710
     const href = posixPathToFileHref(modulePath)
-    const filename = modulePath
-    const dirname = posixDirname(modulePath)
-    const meta: ModuleRunnerImportMeta = {
-      filename: isWindows ? toWindowsPath(filename) : filename,
-      dirname: isWindows ? toWindowsPath(dirname) : dirname,
-      url: href,
-      env: this.envProxy,
-      resolve(_id, _parent?) {
-        throw new Error(
-          '[module runner] "import.meta.resolve" is not supported.',
-        )
-      },
-      // should be replaced during transformation
-      glob() {
-        throw new Error(
-          `[module runner] "import.meta.glob" is statically replaced during ` +
-            `file transformation. Make sure to reference it by the full name.`,
-        )
-      },
-    }
+    const meta = await createImportMeta(modulePath)
     const exports = Object.create(null)
     Object.defineProperty(exports, Symbol.toStringTag, {
       value: 'Module',
diff --git a/packages/vite/src/module-runner/types.ts b/packages/vite/src/module-runner/types.ts
@@ -105,6 +105,14 @@ export interface ModuleRunnerOptions {
    * @default true
    */
   hmr?: boolean | ModuleRunnerHmr
+  /**
+   * Create import.meta object for the module.
+   *
+   * @default createDefaultImportMeta
+   */
+  createImportMeta?: (
+    modulePath: string,
+  ) => ModuleRunnerImportMeta | Promise<ModuleRunnerImportMeta>
   /**
    * Custom module cache. If not provided, creates a separate module cache for each ModuleRunner instance.
    */
diff --git a/packages/vite/src/node/ssr/runtime/__tests__/fixtures/worker.invoke.mjs b/packages/vite/src/node/ssr/runtime/__tests__/fixtures/worker.invoke.mjs
@@ -1,7 +1,7 @@
 // @ts-check
 
 import { BroadcastChannel, parentPort } from 'node:worker_threads'
-import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'
+import { ESModulesEvaluator, ModuleRunner, createNodeImportMeta } from 'vite/module-runner'
 import { createBirpc } from 'birpc'
 
 if (!parentPort) {
@@ -27,6 +27,7 @@ const runner = new ModuleRunner(
         return rpc.invoke(data)
       },
     },
+    createImportMeta: createNodeImportMeta,
     hmr: false,
   },
   new ESModulesEvaluator(),
diff --git a/packages/vite/src/node/ssr/runtime/__tests__/fixtures/worker.mjs b/packages/vite/src/node/ssr/runtime/__tests__/fixtures/worker.mjs
@@ -1,7 +1,7 @@
 // @ts-check
 
 import { BroadcastChannel, parentPort } from 'node:worker_threads'
-import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'
+import { ESModulesEvaluator, ModuleRunner, createNodeImportMeta } from 'vite/module-runner'
 
 if (!parentPort) {
   throw new Error('File "worker.js" must be run in a worker thread')
@@ -24,6 +24,7 @@ const messagePortTransport = {
 const runner = new ModuleRunner(
   {
     transport: messagePortTransport,
+    createImportMeta: createNodeImportMeta,
   },
   new ESModulesEvaluator(),
 )
diff --git a/packages/vite/src/node/ssr/runtime/serverModuleRunner.ts b/packages/vite/src/node/ssr/runtime/serverModuleRunner.ts
@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import type { HotPayload } from 'types/hmrPayload'
-import { ModuleRunner } from 'vite/module-runner'
+import { ModuleRunner, createNodeImportMeta } from 'vite/module-runner'
 import type {
   ModuleEvaluator,
   ModuleRunnerHmr,
@@ -130,6 +130,7 @@ export function createServerModuleRunner(
         channel: environment.hot as NormalizedServerHotChannel,
       }),
       hmr,
+      createImportMeta: createNodeImportMeta,
       sourcemapInterceptor: resolveSourceMapOptions(options),
     },
     options.evaluator,
diff --git a/packages/vite/src/node/ssr/ssrModuleLoader.ts b/packages/vite/src/node/ssr/ssrModuleLoader.ts
@@ -1,6 +1,10 @@
 import colors from 'picocolors'
 import type { EvaluatedModuleNode } from 'vite/module-runner'
-import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'
+import {
+  ESModulesEvaluator,
+  ModuleRunner,
+  createNodeImportMeta,
+} from 'vite/module-runner'
 import type { ViteDevServer } from '../server'
 import { unwrapId } from '../../shared/utils'
 import type { DevEnvironment } from '../server/environment'
@@ -69,6 +73,7 @@ class SSRCompatModuleRunner extends ModuleRunner {
         transport: createServerModuleRunnerTransport({
           channel: environment.hot as NormalizedServerHotChannel,
         }),
+        createImportMeta: createNodeImportMeta,
         sourcemapInterceptor: false,
         hmr: false,
       },
diff --git a/playground/ssr/__tests__/ssr.spec.ts b/playground/ssr/__tests__/ssr.spec.ts
@@ -44,6 +44,14 @@ test(`deadlock doesn't happen for dynamic imports`, async () => {
   )
 })
 
+test(`import.meta.resolve is supported`, async () => {
+  await page.goto(`${url}/import-meta`)
+
+  const metaUrl = await page.textContent('.import-meta-url')
+  expect(metaUrl).not.toBe('')
+  expect(await page.textContent('.import-meta-resolve')).toBe(metaUrl)
+})
+
 test.runIf(isServe)('html proxy is encoded', async () => {
   await page.goto(
     `${url}?%22%3E%3C/script%3E%3Cscript%3Econsole.log(%27html%20proxy%20is%20not%20encoded%27)%3C/script%3E`,
diff --git a/playground/ssr/src/app.js b/playground/ssr/src/app.js
@@ -7,6 +7,7 @@ const pathRenderers = {
   '/circular-import2': renderCircularImport2,
   '/forked-deadlock-static-imports': renderForkedDeadlockStaticImports,
   '/forked-deadlock-dynamic-imports': renderForkedDeadlockDynamicImports,
+  '/import-meta': renderImportMeta,
 }
 
 export async function render(url, rootDir) {
@@ -60,3 +61,12 @@ async function renderForkedDeadlockDynamicImports(rootDir) {
   await commonModuleExport()
   return `<div class="forked-deadlock-dynamic-imports">rendered</div>`
 }
+
+async function renderImportMeta(rootDir) {
+  const metaUrl = import.meta.url
+  const resolveResult = import.meta.resolve('./app.js')
+  return (
+    `<div class="import-meta-url">${escapeHtml(metaUrl)}</div>` +
+    `<div class="import-meta-resolve">${escapeHtml(resolveResult)}</div>`
+  )
+}

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`// @ts-check`
`2`	`2`
`3`	`3`	`import { BroadcastChannel, parentPort } from 'node:worker_threads'`
`4`		`-import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'`
	`4`	`+import { ESModulesEvaluator, ModuleRunner, createNodeImportMeta } from 'vite/module-runner'`
`5`	`5`
`6`	`6`	`if (!parentPort) {`
`7`	`7`	`throw new Error('File "worker.js" must be run in a worker thread')`
`@@ -24,6 +24,7 @@ const messagePortTransport = {`
`24`	`24`	`const runner = new ModuleRunner(`
`25`	`25`	`{`
`26`	`26`	`transport: messagePortTransport,`
	`27`	`+ createImportMeta: createNodeImportMeta,`
`27`	`28`	`},`
`28`	`29`	`new ESModulesEvaluator(),`
`29`	`30`	`)`