fix(hmr): allow watch-only mode without loader internals

Author: XuJianrui

packages/hmr/src/index.ts

@@ -51,7 +51,7 @@ interface Reload {
 class Hmr extends Service {
   public baseDir: string
 
-  private internal: ModuleLoader
+  private internal: ModuleLoader | undefined
   private watcher!: FSWatcher
 
   /**
@@ -77,8 +77,8 @@ class Hmr extends Service {
 
   constructor(ctx: Context, public config: Hmr.Config) {
     super(ctx, 'hmr')
-    if (!this.ctx.loader.internal) {
-      throw new Error('--expose-internals is required for HMR service')
+    if (this.config.root.length && !this.ctx.loader.internal) {
+      throw new Error('HMR module reload requires loader internals: run with --expose-internals or use watch-only mode (root: [])')
     }
     this.internal = this.ctx.loader.internal
     this.baseDir = fileURLToPath(new URL(config.base || '.', ctx.baseUrl))
@@ -88,9 +88,9 @@ class Hmr extends Service {
    * Resolve a module specifier to a URL, compatible with Node 22-24.
    */
   private async _resolve(specifier: string, parentURL: string, attrs: ImportAttributes): Promise<ResolveResult> {
-    switch (this.internal.version) {
-      case 'v1': return await this.internal.resolve(specifier, parentURL, attrs)
-      case 'v2': return this.internal.resolveSync(parentURL, { specifier, attributes: attrs })
+    switch (this.internal!.version) {
+      case 'v1': return await this.internal!.resolve(specifier, parentURL, attrs)
+      case 'v2': return this.internal!.resolveSync(parentURL, { specifier, attributes: attrs })
     }
   }
 
@@ -114,10 +114,12 @@ class Hmr extends Service {
 
     // Collect externals: framework modules reachable from the main entry.
     // Changes to these files require a full process restart, not HMR.
+    // In watch-only mode (root: []) no module reload happens, so externals
+    // tracking is meaningless and loader internals may be unavailable.
     const mainUrl = pathToFileURL(resolve(process.argv[1])).href
-    const mainJob = this.internal.loadCache.get(mainUrl)
-    if (mainJob) {
-      this.externals = await loadDependencies(mainJob)
+    if (this.config.root.length) {
+      const mainJob = this.internal!.loadCache.get(mainUrl)
+      this.externals = mainJob ? await loadDependencies(mainJob) : new Set()
     } else {
       this.externals = new Set()
     }
@@ -135,7 +137,7 @@ class Hmr extends Service {
       // Partial reload: the file is in the ESM loadCache
       // In Node 24, both CJS and ESM modules imported via import() end up
       // in loadCache, so this check covers all module formats.
-      if (loader.internal!.loadCache.has(url)) {
+      if (this.internal?.loadCache.has(url)) {
         this.stashed.add(url)
         return partialReload()
       }
@@ -158,7 +160,7 @@ class Hmr extends Service {
   ]
 
   async getLinked(url: string) {
-    const job = this.internal.loadCache.get(url)
+    const job = this.internal?.loadCache.get(url)
     if (!job) return []
     const linked = await job.linked
     return Array.prototype.map.call(linked, (job: ModuleJob) => job.url) as string[]
@@ -245,7 +247,7 @@ class Hmr extends Service {
         try {
           const { url } = await this._resolve(name, baseUrl, {})
           if (this.declined.has(url)) continue
-          const job = this.internal.loadCache.get(url)
+          const job = this.internal!.loadCache.get(url)
           const plugin = this.ctx.loader.unwrapExports(job?.module?.getNamespace())
           if (!job || !plugin) continue
           pending.set(job, plugin)
@@ -292,9 +294,9 @@ class Hmr extends Service {
     const require = createRequire(import.meta.url)
     for (const filename of this.accepted) {
       // Backup and clear ESM loadCache
-      const job = Map.prototype.get.call(this.internal.loadCache, filename)
+      const job = Map.prototype.get.call(this.internal!.loadCache, filename)
       esmBackup[filename] = job
-      Map.prototype.delete.call(this.internal.loadCache, filename)
+      Map.prototype.delete.call(this.internal!.loadCache, filename)
 
       // Backup and clear CJS Module._cache
       try {
@@ -310,7 +312,7 @@ class Hmr extends Service {
 
     const rollback = () => {
       for (const filename in esmBackup) {
-        Map.prototype.set.call(this.internal.loadCache, filename, esmBackup[filename])
+        Map.prototype.set.call(this.internal!.loadCache, filename, esmBackup[filename])
       }
       for (const filepath in cjsBackup) {
         require.cache[filepath] = cjsBackup[filepath]

packages/hmr/tests/index.spec.ts

@@ -1,12 +1,14 @@
 import { Context, Fiber } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Logger from '@cordisjs/plugin-logger-console'
+import Timer from '@cordisjs/plugin-timer'
+import Hmr from '@cordisjs/plugin-hmr'
 import { writeFileSync, readFileSync, unlinkSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { expect, describe, it, beforeAll, afterAll, afterEach } from 'vitest'
-import { pathToFileURL } from 'node:url'
+import { pathToFileURL, fileURLToPath } from 'node:url'
 
-const testDir = new URL('.', import.meta.url).pathname
+const testDir = fileURLToPath(new URL('.', import.meta.url))
 
 // Helper: read and backup a file, returning restore function
 function backupFile(filename: string) {
@@ -797,4 +799,42 @@ export function apply(ctx: Context) {
       expect(ctx.bail('hmr-test/get-value')).to.equal('stash-test-2')
     }, 10000)
   })
+
+  // ===== Watch-only without loader internals =====
+  // Regression: the constructor used to require `loader.internal`
+  // unconditionally, but watch-only mode (root: []) never touches module
+  // reload, so it must boot even when the native helper binding is missing.
+  describe('watch-only without loader internals', () => {
+    it('should start in watch-only mode without loader internals', async () => {
+      const ctx = new Context()
+      ctx.baseUrl = pathToFileURL(resolve(testDir) + '/').href
+      await ctx.plugin(Logger)
+      await ctx.plugin(Timer)
+      const fiber = await ctx.plugin(Loader)
+      // Simulate a missing native helper binding: fromInternal() returns
+      // undefined in production when the addon cannot resolve.
+      ctx.loader.internal = undefined
+
+      await ctx.plugin(Hmr, { root: [], debounce: 100, ignored: [] })
+
+      expect(ctx.hmr).to.be.ok
+      fiber?.dispose()
+      await new Promise(r => setTimeout(r, 200))
+    }, 10000)
+
+    it('should still require loader internals for module reload', async () => {
+      const ctx = new Context()
+      ctx.baseUrl = pathToFileURL(resolve(testDir) + '/').href
+      await ctx.plugin(Logger)
+      await ctx.plugin(Timer)
+      const fiber = await ctx.plugin(Loader)
+      ctx.loader.internal = undefined
+
+      await expect(ctx.plugin(Hmr, { root: ['.'], debounce: 100, ignored: [] }))
+        .rejects.toThrow(/loader internals/)
+
+      fiber?.dispose()
+      await new Promise(r => setTimeout(r, 200))
+    }, 10000)
+  })
 })