Plugin patch hot-reload re-runs apply() but keeps already-imported ESM modules cached

[Dogwind221]

What I did

I'm developing a local plugin registered through a profile patch:

- insert:
    - id: live-workbench
      name: 'file:///F:/.../plugin/dsh-live-workbench/dist/plugin.js'

The plugin's apply() dynamically imports a handler module that lives elsewhere in my repo, then registers a prefix route with it:

export const inject = ['webServer'];

export function apply(ctx, config) {
  ctx.effect(() => {
    // 带 query 的动态 import：每次重载都拿到全新模块实例
    import(`${HANDLER_URL}?v=${Date.now()}`).then(({ createWorkbenchHandler }) => {
      disposeRoute = ctx.webServer.register({
        kind: 'prefix',
        path: basePath,
        handler: createWorkbenchHandler({ basePath }),
      });
    });
    return () => disposeRoute();
  });
}

What I expected

Editing the handler module and touching cordis.patch.yml should reload the plugin so the new code takes effect — i.e. the documented behaviour that a patch change hot-reloads without restarting DSH.

What actually happened

apply() runs again (my activation breadcrumb confirms it: a new apply() line is appended on every patch touch), but the module it imports is not re-evaluated. Node's ESM cache is keyed by the resolved URL, so the GUI keeps serving the old handler until I restart DSH entirely.

Workaround

Bust the cache manually on every load, as in the snippet above:

import(`${HANDLER_URL}?v=${Date.now()}`)

It works, but the reload is only "real" if the plugin author knows to do this. A plugin that imports statically gets a silently stale engine after a patch reload.

Questions

1. Is this intended? If so, it would help to document it right next to the hot-reload behaviour — currently the two facts ("patch changes hot-reload" and "imported modules stay cached") lead to opposite conclusions.
2. Could the loader invalidate the changed plugin's module subtree (or at least log "reloaded entry, imported modules unchanged")?

Environment

• DSH desktop, plugins registered through a profile cordis.patch.yml with file:// paths
• Plugin host half: ESM, inject: ['webServer'], prefix route registration

[Muguett-DBY]

Check the HMR watch scope first. DSH already has a module-replacement path, separate from reapplying plugin configuration.

In the current source (687f282), the base bundle sets hmr.config.root to []: configuration files are watched, but source-module watching is off. Profile recomposition also checks loaded files under the profile directory and linked-package targets. A file:// plugin elsewhere on F: is not automatically one of those roots merely because the patch references it; profileRoots() defines that scope.

For development, configure the existing hmr entry before launching, using the directory containing your plugin and handler:

- id: hmr
  disabled: false
  config:
    base: 'file:///F:/path/to/your/repo/'
    root: ['.']

Replace that example URL with your repository directory, including the trailing slash. You can narrow root to the build-output directories once both files are covered. The default ignores include node_modules and hidden paths. Keep the plugin's registration URL stable; source edits, rather than patch touches, should be the reload trigger for this setup.

There is also a limit to the timestamp workaround: changing the handler URL does not change the URLs of its static imports. I checked this on Node 22.23.4 and 26.12.1 with handler.mjs importing ./helper.mjs: after editing the helper, importing handler.mjs?revision=2 re-evaluates the handler but still reads the old helper. Importing the helper separately with a query doesn't rewire that handler either. Node documents the URL-based cache.

DSH's documented replacement path follows static module links; its limitations section distinguishes dynamic imports, existing Workers and TSX loader caches. For a handler that can be imported statically, that gives HMR a dependency path back to the plugin to replace.

This is a source check plus a standalone Node reproduction, not verification of your packaged Desktop build. If that build differs, the source behavior above may not all be present there.

[Dogwind221]

Thanks — that explains it, and it matches what I see: my plugin is a file:// path on another drive, so it never entered the HMR roots, and I was "reloading" by touching the patch instead of editing the source.

Three things on my side:

1. I'll configure the existing hmr entry as you describe (config.base = my repo directory with a trailing slash) and keep the registration URL stable. I'll report back whether source edits then replace the module in the packaged Desktop build — your note that this is a source check only is fair, and my environment is the packaged one.

2. My ?v=timestamp workaround now has a known ceiling, as you showed: it re-evaluates the handler but not its static imports. My handler is not a single file — server/lib/handler.mjs imports a dozen siblings — so busting only the top file was never going to be a real reload. Switching to a static import so HMR gets a dependency path is the right fix, and I'll verify that replacement then reaches the sibling modules too.

3. Related, possibly the same root cause: I hit a case where a query string in a registration path (plugin.js?v=2) made the package name resolve incorrectly, the plugin loaded twice, and boot failed on a duplicate prefix route — A query string in a plugin's file:// path causes a duplicate load and a duplicate route #10775. If query strings are never supported in file:// paths, rejecting them up front would turn that into a clear error instead of a duplicate-route stack.

If this is by design rather than a gap, one sentence in the plugin docs — "a file:// plugin outside the profile directory is not watched unless it is under hmr.config.base" — would have saved me the restart loop. Happy to draft that if useful.

[Muguett-DBY]

Yes, that matches the watch-scope distinction. One detail to keep in the test and proposed docs: set root explicitly as well as base. The base bundle supplies root: [], so changing base alone leaves source watching off. base anchors the relative paths; root selects what gets watched (configuration).

For your current layout, after the broad root: ['.'] check, root: ['plugin/dsh-live-workbench/dist', 'server'] would cover the host entry, handler and its server-side siblings. Testing one edit in the handler and a separate edit in a statically imported sibling should distinguish entry reload from dependency reload. That packaged-Desktop result will be useful; I haven't verified that part locally.

I'd keep #10775 separate from a blanket ban on query strings: Node supports them as distinct module identities. Whether DSH should reject them for plugin registration is a loader-contract decision. A clean, stable registration URL avoids that ambiguity while you test source HMR.

[Dogwind221]

Thanks — the root/base distinction was the missing piece, and I have the packaged-Desktop results you asked for.

Config now (both desktop and web profiles):

- id: hmr
  disabled: false
  config:
    base: 'file:///F:/dsh/直播工作台/'
    root:
      - 'plugin/dsh-live-workbench'
      - 'server'

Two-phase test — a small script appends a marker comment to one file, polls my plugin's activation breadcrumb for a new apply()/activated pair, then restores the file:

1. Broad check, root: ['.'] — both cases reload:

• edit server/lib/handler.mjs (entry) → new activation pair (log 198 → 204 lines)
• edit server/lib/paths.mjs (statically imported by the handler) → new activation pair (204 → 210)

2. Narrowed, root: ['plugin/dsh-live-workbench', 'server'] — both still reload:

• handler edit → reload
• paths.mjs edit → reload

So on the packaged build the behaviour matches your description: entry reload alone is not the whole story, and with root set the dependency reload does reach the statically imported sibling. I widened your suggested plugin/dsh-live-workbench/dist to plugin/dsh-live-workbench so the client artifact (client/client.js) stays in scope — say if that looks over-broad.

One honest data point for the source/packaged difference you flagged: with base only (no root) I had observed a reload after editing the handler, which is why I assumed it worked. I never edited a sibling at that point, so I can't tell from that run whether dependency reload was working or whether the entry reload came from a different path in the packaged build. With root set explicitly, both cases pass and the result no longer depends on that ambiguity.

I also switched the plugin's host entry to a static import of the handler (the dynamic ?v= import is gone), which is what gives HMR a dependency path at all. Route registration stays inside a try/catch, but module evaluation failure now fails the plugin loudly instead of being swallowed.

Docs + the verification script are in Dogwind221/Dw-LiveWorkbench#3 (README §6 states that base alone leaves watching off).

[Muguett-DBY]

Watching plugin/dsh-live-workbench looks reasonable for that layout. It keeps the client artifact in scope, and the default ignored patterns include **/.*, so .activation.log should not trigger a reload loop (source). Watching the client file is separate from verifying that an open browser has loaded its new code.

I found one issue in the verification script while reviewing #3: it passes even if the new log lines only say activate failed. Restoring the handler can also produce a delayed reload during the dependency test. That doesn't disprove your Desktop result, but the script needs stronger evidence before it can confirm it.

I've sent a fix with seven regression cases. Each sampled module now has its own temporary evaluation marker, followed by a check for successful activation. The fixtures pass locally; I haven't run the revised probe in packaged Desktop.