Server-side modules do not update via HMR when imported dependencies change

[devcustrom]

Astro Info

Astro                    v5.16.5
Vite                     v6.4.1
Node                     v20.19.5
System                   Windows (x64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

When using HMR (Hot Module Replacement) in Astro during development, server-side modules that import other modules (e.g., store files) do not reload when those imported dependencies are modified. The server-side code continues to use the cached version of the imported module's code until the development server is restarted.

To Reproduce

• Clone the example repository: git clone https://github.com/devcustrom/astro-pinia-bug.git
• Run npm install and then npm run dev.
• Open the main page in a browser. You should see the message "test value: 123" printed in both the terminal and the browser console.
• Now, edit src/store/teststore.ts: change the text inside the console.log on line 6 (for example, to console.log('test updated!')).
• Save the file and observe:
  • Client Side: A new message (e.g., test updated!) will appear in the browser console if the client component also imports and uses teststore.ts. HMR works on the client.
  • Server Side: The message in the terminal, originating from server-only-store.ts (which imports teststore.ts), will not update. Or, if server-only-store.ts renders a result into the HTML, that result will not change until the page is reloaded, and even then, it might still show the old value if the server module wasn't reloaded.
• Restart the Astro dev server (Ctrl+C and npm run dev again).
• Refresh the page in the browser. Now, the console.log from server-only-store.ts will print the new message, and any server-side HTML dependent on this store will also update correctly.

Expected Behavior

When src/store/teststore.ts changes, any server-side modules importing it (e.g., server-only-store.ts) should be notified by HMR and re-run to reflect the changes. This should result in the console.log in the terminal updating and any server-rendered HTML depending on this store updating correctly.

What's the expected result?

Server-side modules (server-only-store.ts) do not reload when their dependencies (teststore.ts) change. They continue using the cached version of the imported code until the entire development server is restarted. HMR works correctly on the client side.

Link to Minimal Reproducible Example

https://github.com/devcustrom/astro-pinia-bug

Participation

• I am willing to submit a pull request for this issue.

[aldoprogrammer]

I opened a PR that fixes SSR HMR invalidation and adds a regression test: #15128

Demo video: https://youtu.be/-wjCxZHey7M

Note: the original Pinia repro uses a global Pinia instance, which caches across SSR requests. Creating a new Pinia per request resolves that part; with the PR, SSR dependency changes re-run as expected.

[matthewp]

Triage bot, please take a look at this one and see if you can find a fix.

[github-actions]

I was able to reproduce this issue. The bug was reproduced on Astro v6 (current monorepo) using a simplified global singleton cache pattern that mimics Pinia's createPinia() + defineStore() behavior. When a store definition module (data.ts) is edited, the server-side rendered value remains stale until the dev server is restarted.

Fix: I was able to fix this issue. The fix adds a call to evaluatedModules.clear() on the SSR runner inside the astro:hmr-reload plugin's hotUpdate handler, so that module-level state in dependencies (e.g., global singletons like Pinia stores) is re-evaluated on the next request instead of being served from stale cache. View Fix

Cause: Vite's SSR module invalidation only walks UP through importers, so dependency modules like registry.ts (which hold global singleton state) are never invalidated — and the SSR runner's evaluatedModules cache was also never cleared by Astro's astro:hmr-reload plugin, causing stale module-level state to persist across HMR updates.

Impact: Any Astro user relying on module-level singleton state in server-side code (e.g., Pinia stores, global registries, or any module using a cached Map/Set/Object at the top level) will see stale values after HMR updates during development, requiring a full dev server restart to pick up changes.

Full Triage Report

Issue #15021: Server-side modules do not update via HMR when imported dependencies change

Original Issue Details

Title: Server-side modules do not update via HMR when imported dependencies change

Reporter's Environment:

• Astro v5.16.5
• Vite v6.4.1
• Node v20.19.5
• Windows (x64)
• Output: static
• Package Manager: npm
• No adapter, no integrations

Description: When using HMR in Astro during development, server-side modules that import other modules (e.g., store files) do not reload when those imported dependencies are modified. The server-side code continues to use the cached version of the imported module's code until the development server is restarted.

Original Reproduction Repository: https://github.com/devcustrom/astro-pinia-bug

The reproduction uses Pinia (Vue state management) with a global createPinia() singleton. The issue manifests when:

1. pinia.ts exports a global Pinia instance via createPinia()
2. teststore.ts defines a store with defineStore (which registers in the Pinia cache)
3. index.astro imports both and uses the store server-side
4. When teststore.ts is edited, the Pinia singleton's internal cache is NOT cleared, so the old store definition persists

Expected Behavior: When src/store/teststore.ts changes, any server-side modules importing it should be notified by HMR and re-run to reflect the changes.

Relevant Comment: A contributor (aldoprogrammer) opened PR #15128 to fix SSR HMR invalidation, noting that "the original Pinia repro uses a global Pinia instance, which caches across SSR requests. Creating a new Pinia per request resolves that part."

Reproduction Results

Status: REPRODUCED

The bug was successfully reproduced using a simplified pattern that mimics Pinia's global singleton caching behavior. We tested on Astro v6.0.0-beta.11 (current workspace version).

What Was Tested

Test 1: Simple module dependency (NO global cache) — WORKS CORRECTLY

Setup:

• data.ts exports a simple constant testValue
• server-module.ts imports testValue from data.ts
• index.astro imports from server-module.ts and renders the value

Result: When data.ts is modified, the next page request correctly shows the updated value. Vite's SSR module invalidation properly invalidates data.ts and all its importers (server-module.ts, index.astro). All modules are re-evaluated on the next request.

Test 2: Global singleton cache pattern (mimics Pinia) — BUG REPRODUCED

Setup:

• registry.ts — a module that holds a global Map<string, any> cache and exports a defineStore() function (equivalent to Pinia's createPinia() + defineStore())
• data.ts — imports defineStore from registry.ts and registers a store with value "original-value-123"
• server-module.ts — imports and uses the store from data.ts
• index.astro — renders the store value server-side

Import chain: index.astro → server-module.ts → data.ts → registry.ts

Steps to reproduce:

1. Start dev server: pnpm astro dev --port 14321
2. Fetch http://localhost:14321/ — shows "Server value: original-value-123" ✓
3. Edit data.ts: change the store value from "original-value-123" to "updated-value-456"
4. Fetch http://localhost:14321/ again — still shows "Server value: original-value-123" ✗
5. Restart dev server
6. Fetch again — shows "Server value: updated-value-456" ✓

Server logs confirm the bug mechanism:

[SERVER] registry: Creating store 'test'        ← Initial load: store created
[SERVER] data.ts: store setup function running
[SERVER] server-module: store value: original-value-123
[SERVER] index.astro frontmatter, serverValue: original-value-123

[SERVER] registry: Using CACHED store 'test'    ← After HMR: registry uses stale cache!
[SERVER] server-module: store value: original-value-123  ← Old value!
[SERVER] index.astro frontmatter, serverValue: original-value-123  ← Old value!

Root Cause Analysis

The bug occurs because of how Vite's SSR module invalidation propagates:

1. When data.ts changes, Vite invalidates data.ts and all modules that import it (its importers: server-module.ts, index.astro).
2. However, registry.ts is NOT invalidated because it is a dependency of data.ts, not an importer. registry.ts itself didn't change.
3. Since registry.ts's module-level state (the storeCache Map) persists in memory, when data.ts re-evaluates and calls defineStore(), the registry returns the cached store from the old evaluation.

This is the exact same pattern used by Pinia: createPinia() creates a singleton with an internal store cache. When dependent modules are re-evaluated via HMR, the Pinia instance still holds the old store definitions.

Where the fix likely needs to happen

The key file for SSR HMR invalidation is:

• packages/astro/src/vite-plugin-hmr-reload/index.ts — The astro:hmr-reload plugin runs as the last hotUpdate handler. It checks if changed modules are SSR-only (not in client module graph) and manually invalidates them + triggers full browser reload.

The current invalidation in astro:hmr-reload only invalidates the directly changed modules (the ones Vite passes in modules). It does NOT walk the full dependency tree to also invalidate modules that the changed module depends on (downstream dependencies).

A potential fix would be to also invalidate the full dependency subtree of changed modules — i.e., when data.ts changes, also invalidate registry.ts (because data.ts imports from registry.ts). This would clear registry.ts's module-level state and force it to re-evaluate, creating a fresh storeCache Map.

However, this approach needs careful consideration because blindly invalidating all transitive dependencies could cause excessive re-evaluation and potentially break other things. An alternative approach (mentioned in PR #15128) might be to invalidate the full SSR module graph more aggressively, similar to how Vite handles this internally.

Other relevant files in the HMR pipeline:

• packages/astro/src/vite-plugin-astro/hmr.ts — Handles .astro file HMR (style-only optimization)
• packages/astro/src/core/module-loader/vite.ts — ModuleLoader abstraction wrapping Vite's SSR environment
• packages/astro/src/vite-plugin-astro-server/controller.ts — Dev server controller, handles error-state invalidation

Diagnosis

Confidence: high

Root Cause

The bug is caused by a gap between two separate module caches in Vite's SSR architecture that Astro's astro:hmr-reload plugin does not bridge:

1. EnvironmentModuleGraph (server-side) — Vite's module graph tracking transform results, import relationships, and HMR state. This is what this.environment.moduleGraph.invalidateModule() operates on.
2. ModuleRunner.evaluatedModules (EvaluatedModules) — The SSR runner's own cache of evaluated (executed) module exports/state. This is completely separate from the server-side module graph.

The Invalidation Flow (Current Behavior)

When a file like data.ts changes:

1. Server-side invalidateModule() (Vite's EnvironmentModuleGraph) clears transformResult, ssrModule, and ssrError on the changed module, then walks UP through importers recursively. So data.ts, server-module.ts, and index.astro all get their server-side transform caches cleared. However, registry.ts (a dependency, not an importer) is NOT invalidated.

2. The SSR runner's EvaluatedModules cache is NEVER cleared. The astro:hmr-reload plugin sends server.ws.send({ type: 'full-reload' }) which goes to the browser WebSocket, not to the SSR runner's hot channel. The SSR runner has its own separate hot channel (environment.hot), and only a full-reload received through THAT channel would trigger runner.evaluatedModules.clear().

3. When the page is re-requested, the SSR runner's ModuleRunner.import() calls cachedRequest() for each module in the import chain:

   • For data.ts (invalidated server-side): The server returns { invalidate: true } from fetchModule() because transformResult was cleared. The runner then calls evaluatedModules.invalidateModule() on data.ts, clearing its promise and exports, forcing re-evaluation.
   • For registry.ts (NOT invalidated server-side): The server returns { cache: true } from fetchModule() because transformResult still exists. The runner short-circuits in cachedRequest() because mod.promise is still populated. The old storeCache Map persists in memory.

4. When data.ts re-evaluates and calls import { defineStore } from './registry.ts', the runner returns registry.ts's cached exports (with the old storeCache Map). defineStore('test', ...) finds the cached entry and returns the old value.

Affected Files

The fix is needed in one file:

• packages/astro/src/vite-plugin-hmr-reload/index.ts (line 44-47) — The if (hasSsrOnlyModules) block needs to also clear the SSR runner's evaluatedModules cache before sending full-reload to the browser.

Verified Fix

The fix has been tested and confirmed working. Add evaluatedModules.clear() to the astro:hmr-reload plugin's hotUpdate handler:

// In packages/astro/src/vite-plugin-hmr-reload/index.ts
import { isRunnableDevEnvironment, type EnvironmentModuleNode, type Plugin } from 'vite';

// ... inside the hotUpdate handler, in the `if (hasSsrOnlyModules)` block:
if (hasSsrOnlyModules) {
    // Clear the SSR runner's evaluated modules cache so that
    // module-level state in dependencies (e.g. global singletons like Pinia stores)
    // is re-evaluated on the next request, not served from stale cache.
    if (isRunnableDevEnvironment(this.environment)) {
        this.environment.runner.evaluatedModules.clear();
    }
    server.ws.send({ type: 'full-reload' });
    return [];
}

Why clear() instead of targeted invalidation:

• evaluatedModules.clear() is what Vite itself calls when processing full-reload through the runner's own hot channel. Since we're already sending full-reload to the browser (which will re-request all pages), clearing the entire runner cache is consistent with the intended semantics.
• A more targeted approach (walking importedModules downward to invalidate only dependencies of changed modules) risks missing modules if the import graph isn't fully populated at HMR time.
• The cost of clear() is negligible: all modules will be re-evaluated on the next request anyway since the browser does a full reload.

Alternative approaches considered but not recommended:

1. Walking importedModules downward — More surgical but fragile; risk of incomplete graphs.
2. Sending full-reload through environment.hot instead of server.ws — Would trigger the runner's built-in full-reload handler which calls evaluatedModules.clear(). However, this changes the semantics of what full-reload means in the SSR context and may have unintended side effects.

Test Results with Fix Applied

Before fix:

[SERVER] registry: Using CACHED store 'test'          ← Stale cache!
[SERVER] server-module: store value: original-value-123  ← Old value

After fix:

[SERVER] registry: Creating store 'test'               ← Fresh evaluation!
[SERVER] data.ts: store setup function running
[SERVER] server-module: store value: updated-value-456   ← New value ✓

Multiple consecutive edits all correctly reflected the new values without needing a server restart.

Fix

Status: FIXED

What Was Changed

File: packages/astro/src/vite-plugin-hmr-reload/index.ts

In the astro:hmr-reload plugin's hotUpdate handler, added a call to this.environment.runner.evaluatedModules.clear() before sending full-reload to the browser. This clears the SSR runner's evaluated modules cache so that module-level state in dependencies (e.g., global singletons like Pinia stores) is re-evaluated on the next request instead of being served from stale cache.

Why This Fix Works

The root cause was a gap between two separate caches:

1. Vite's EnvironmentModuleGraph (server-side transform cache) — invalidated by moduleGraph.invalidateModule()
2. ModuleRunner.evaluatedModules (SSR runner's evaluated JS module cache) — never cleared

When data.ts changes, invalidateModule() walks UP through importers (clearing data.ts, server-module.ts, index.astro), but does NOT invalidate registry.ts (a dependency, not an importer). The SSR runner's evaluatedModules cache was also never cleared, so registry.ts's module-level state (the storeCache Map) persisted.

By calling evaluatedModules.clear(), all SSR modules are forced to re-evaluate on the next request. This is consistent with what Vite itself does when processing full-reload through the runner's own hot channel, and the cost is negligible since we're already sending full-reload to the browser (which will re-request all pages anyway).

Git Diff

diff --git a/packages/astro/src/vite-plugin-hmr-reload/index.ts b/packages/astro/src/vite-plugin-hmr-reload/index.ts
index 355aa03..5fc2e2a 100644
--- a/packages/astro/src/vite-plugin-hmr-reload/index.ts
+++ b/packages/astro/src/vite-plugin-hmr-reload/index.ts
@@ -1,4 +1,4 @@
-import type { EnvironmentModuleNode, Plugin } from 'vite';
+import { isRunnableDevEnvironment, type EnvironmentModuleNode, type Plugin } from 'vite';
 import { ASTRO_VITE_ENVIRONMENT_NAMES } from '../core/constants.js';
 import { VIRTUAL_PAGE_RESOLVED_MODULE_ID } from '../vite-plugin-pages/const.js';
 import { getDevCssModuleNameFromPageVirtualModuleName } from '../vite-plugin-css/util.js';
@@ -42,6 +42,13 @@ export default function hmrReload(): Plugin {
 			}
 
 			if (hasSsrOnlyModules) {
+				// Clear the SSR runner's evaluated modules cache so that
+				// module-level state in dependencies (e.g. global singletons
+				// like Pinia stores) is re-evaluated on the next request,
+				// not served from stale cache.
+				if (isRunnableDevEnvironment(this.environment)) {
+					this.environment.runner.evaluatedModules.clear();
+				}
 				server.ws.send({ type: 'full-reload' });
 				return [];
 			}

Verification Results

Test 1: Single edit

• Initial request: Server value: original-value-123 ✓
• After editing data.ts to change value to updated-value-456
• Next request: Server value: updated-value-456 ✓
• Server logs show registry: Creating store 'test' (fresh evaluation, not cached)

Test 2: Multiple consecutive edits

• Second edit changing to final-value-789
• Next request: Server value: final-value-789 ✓
• All consecutive edits correctly reflected without server restart

Regression Tests:

• test/units/vite-plugin-astro/hmr.test.js: 7/7 pass ✓
• test/hmr-new-page.test.js: 4/4 pass (2 skipped on windows) ✓
• Package build: 0 errors ✓

Alternative Approaches Considered

1. Walking importedModules downward — More surgical but fragile; risks missing modules if the import graph isn't fully populated at HMR time.
2. Sending full-reload through environment.hot instead of server.ws — Would trigger the runner's built-in full-reload handler which calls evaluatedModules.clear(). However, this changes the semantics and may have unintended side effects.
3. Per-module targeted invalidation — Complex and error-prone; clear() is simpler and consistent with Vite's own full-reload semantics.

This report was made by an LLM. Mistakes happen, check important info.

[matthewp]

This is not a bug. When teststore.ts changes it does reload, but that doesn't cause dependants (in your case pinia) from being invalidated. If we did that it would invalidate a large amount of files on every change.

The correct solution here is to use https://vite.dev/guide/api-hmr#hot-accept-cb to invalidate global state when your module changes.

[devcustrom]

This is not a bug. When teststore.ts changes it does reload, but that doesn't cause dependants (in your case pinia) from being invalidated. If we did that it would invalidate a large amount of files on every change.

The correct solution here is to use https://vite.dev/guide/api-hmr#hot-accept-cb to invalidate global state when your module changes.

It turns out that you need to follow this instruction in astro https://pinia.vuejs.org/cookbook/hot-module-replacement.html ?