vite-node: race condition in exports resulting in empty modules

[privatenumber]

Describe the bug

In native ESM, import and export statements are hoisted and fully registered before any top-level code is executed. This ensures that in cyclic dependencies, partial but correct bindings are available to dependent modules.

However, in Vite SSR / vite-node, it appears that export bindings are assigned inline, at the point in code where the export statement occurs, rather than being pre-registered before execution. As a result, in the presence of cyclic dependencies, if a module's top-level code is slow to execute, its exports may not be populated in time for the dependent module.

This causes a race condition where the importer receives an empty module, violating expected ESM semantics.

I'm currently encountering this issue while using Vitest, but the root cause appears to lie within vite-node and Vite SSR.

Reproduction

StackBlitz repro: https://stackblitz.com/edit/vitest-dev-vitest-ta6bnjew?file=README.md

---

This bug occurs because vite-node compiles modules such that export bindings are defined inline, rather than being hoisted like in native ESM.

For example, a.js compiles to something like:

'use strict';async (__vite_ssr_import__,__vite_ssr_dynamic_import__,__vite_ssr_exports__,__vite_ssr_exportAll__,__vite_ssr_import_meta__,require,exports,module,__filename,__dirname)=>{{const __vite_ssr_import_0__ = await __vite_ssr_import__("node:timers/promises", {"importedNames":["setTimeout"]});

__vite_ssr_dynamic_import__("/src/b.js");

await (0,__vite_ssr_import_0__.setTimeout)(1000);

const a = 1;
Object.defineProperty(__vite_ssr_exports__, "a", { enumerable: true, configurable: true, get(){ return a }});
}}

This demonstrates that the export binding for a is not registered until after the setTimeout completes. The setTimeout represents any slow top-level logic. If there's a cyclic dependency, another module may import a.js before its exports are defined, receiving an empty module.

In contrast, native ESM hoists and registers export bindings before any top-level code runs. This guarantees that the export names are accessible—even during execution of slow module code.

As an example of this behavior, you can see this with esbuild compiled code here: https://esbuild.github.io/try/#dAAwLjI1LjIALS1mb3JtYXQ9Y2pzAGNvbnNvbGUubG9nKCdoaScpCgovLyBFdmVuIHRob3VnaCBpdCBsb29rcyBsaWtlIHRoaXMgaXMgZXhwb3J0ZWQgYWZ0ZXIgY29uc29sZS5sb2cKLy8gRVNNIGJlaGF2aW9yIGlzIHRoYXQgaXQgc2hvdWxkIGdldCBleHBvcnRlZCBmaXJzdApleHBvcnQgY29uc3QgYSA9IDE7CgovLyBGWUkgaW1wb3J0cyBhbHNvIGdldCBob2lzdGVkCmltcG9ydCAnZnMn

System Info

N/A

Used Package Manager

npm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[sheremet-va]

This is related more to how Vite SSR transform works, Vitest cannot influence that, so I would recommend opening the issue in the vite repo

[privatenumber]

I think the fix could be made on either side, depending on your rollout strategy. While it's unlikely that anyone relies on this behavior—since browsers run Vite's frontend runs in a strict ESM environment—maintainers may still want to treat it as a breaking change, depending on risk tolerance.

On the vite-node side, a quick fix without being blocked by Vite would be to use a lexer to extract and register imports/exports before the module executes.

On Vite's side, I might expect a more robust compilation step (e.g. using Oxc/esbuild) to properly hoist imports and exports. Will also open an issue there.

[sheremet-va]

vite-node is softly deprecated, so we probably won't be fixing it there. Using a lexer would behave differently than if the getter was defined in the file itself (it will still return undefined), unless you want to inject it in the code.

If I remember correctly, Vite SSR already worked like that before but it lead to some other issues. The current behaviour is less punishing which is the main goal here.

[sheremet-va]

Ah, actually, I remembered the opposite. Vite 6.3 adds this behaviour: vitejs/vite#18983

[privatenumber]

Oh, that's great to hear! Sounds like it’s just a matter of time before it gets released & fixed.

[sheremet-va]

You can see now that it throws an error because the value is accessed before being initialised (which is also what I would expect from this approach, not sure how node resolves this natively): https://stackblitz.com/edit/vitest-dev-vitest-q5enbjwi?file=package.json

ReferenceError: Cannot access 'a' before initialization
    at Module.get (/home/projects/vitest-dev-vitest-ta6bnjew/src/a.js:1:282)
    at eval (/home/projects/vitest-dev-vitest-ta6bnjew/src/b.js:2:44)

Ref @hi-ogawa

[privatenumber]

I looked into it, and I think the issue is that the Vite SSR runtime effectively runs in a CommonJS environment. Because of that, it doesn't support top-level await (which I'm using in the reproduction), leading to that error.

I may be wrong though, and the limitation may possibly be addressed in vite-node's request to behave strictly like await import.

@hi-ogawa
If supporting TLA is a Vite SSR limitation, I'd be happy to file a bug for it.

[sheremet-va]

I may be wrong though, and the limitation may possibly be addressed in vite-node's request to behave strictly like await import.

It does seem like Vite SSR also fails:

ReferenceError: Cannot access 'a' before initialization
    at Module.get [as a] (/home/projects/vitest-dev-vitest-q5enbjwi/src/a.js:3:110)
    at eval (/home/projects/vitest-dev-vitest-q5enbjwi/src/b.js:4:44)

This probably happens because we don't implement the linking phase. Vite SSR and vite-node are basically just async CJS implementations

[hi-ogawa]

vitejs/vite#18983 intends to make Vite SSR closer to esm, but it's known that this unfortunately doesn't solve issues entirely.

For one, as I mentioned in the PR, it cannot hoist export names from export * from "..." since Vite SSR evaluates imports lazily and it doesn't know the export names during the transform. For bundler, this is not an issue since they statically analyze module exports.

For 2nd, TLA is also a different monster and addressing it on Vite is out-of-scope since rollup and esbuild doesn't implement it correctly either, so the build result can cause inconsistency in a different way. There is an interesting repo by evanw https://github.com/evanw/tla-fuzzer and Vite SSR works similar to "Import becomes inline await" strategy and so does Rollup.
(Also Rolldown's support will be similar to rollup https://rolldown.rs/guide/in-depth/tla-in-rolldown)

I may be wrong though, and the limitation may possibly be addressed in vite-node's request to behave strictly like await import.

@hi-ogawa If supporting TLA is a Vite SSR limitation, I'd be happy to file a bug for it.

@privatenumber From what I understand, supporting TLA close to esm sematics is not simple. But, having said that, I think no one has made a proper issue, so feel free to create one. We might close it later as out-of-scope though.

(Also, one note that vitejs/vite#18983 might actually cause too much churn since it turns currently silenced undefined into a hard error. So depending on the situation after 6.3 release, reverting it might not be an out-of-question 🙃)

[privatenumber]

Thanks for the detailed response, @hi-ogawa.

Hoisting exports resolves the initial problem I encountered where I was getting an empty module. But the second problem is that Vite SSR rewrites static imports into awaited dynamic imports. This effectively injects TLA where there wasn't any, which sometimes errors when accessing the hoisted export with Cannot access '...' before initialization (race condition).

Here's an example transformation of one of the affected files

async (__vite_ssr_import__,__vite_ssr_dynamic_import__,__vite_ssr_exports__,__vite_ssr_exportAll__,__vite_ssr_import_meta__,require,exports,module,__filename,__dirname)=>{{
    
Object.defineProperty(
    __vite_ssr_exports__,
    "MyExport",
    {
        enumerable: true,
        configurable: true,
        get(){
            /* ReferenceError: Cannot access 'MyExport' before initialization */
            return MyExport
        }
    }
);

// TLA is injected by Vite SSR
const __vite_ssr_import_0__ = await __vite_ssr_import__("/@fs/some-pkg/dist/esm/index-fb35cab8.js", {"importedNames":["r","c","h","H","g"]});
const __vite_ssr_import_1__ = await __vite_ssr_import__("/@fs/some-pkg/dist/esm/index-9e6efb14.js", {"importedNames":["c"]});
const __vite_ssr_import_2__ = await __vite_ssr_import__("/@fs/some-pkg/dist/esm/classnames-84eaa2b2.js", {"importedNames":["c"]});
// More dynamic imports...

const MyExport = 1;
}}

The minimal reproduction @sheremet-va shared above demonstrates the same limitation. In this example, the await setTimeout() simulates the list of SSR-injected dynamic imports. Removing it, or using a sync sleep resolves the issue.

If Vite SSR is going to transform ESM to CJS, it should probably preserve CJS semantics—meaning __vite_ssr_import__ needs to behave more like a synchronous require. Alternatively, maybe it could register a Node.js loader for instrumentation and leverage native ESM.

[spaceemotion]

Just came across this issue, because I felt like I was going crazy. Tests suddenly stopped working, but I guess cyclical imports generally are a bad thing.

However, we have a case where two modules can't be combined, and do depend on each other. It's just that the method calls are fine when looked at in isolation (like method A() calls method B(), and B() calls A() if a certain condition is met - recursively between each other.

I can't seem to be able to resolve this properly with the current Vite 6.3 update.

What's even weirder, is that it all seems to be working fine, until I make completely unrelated changes. Then, suddenly Vitest - correctly - identifies a cycle, and the associated tests break. Why it doesn't do that in the first place for all occurrences, I don't know.

Edit: I was able to resolve it by extracting calls into separate files, which I guess made A and B now depend on C, even if C does not break the cycle, just allows offloading the imports?

[hi-ogawa]

If Vite SSR is going to transform ESM to CJS, it should probably preserve CJS semantics—meaning vite_ssr_import needs to behave more like a synchronous require. Alternatively, maybe it could register a Node.js loader for instrumentation and leverage native ESM.

Yes, node loader is likely required to preserve top-level-await semantics properly. Or maybe it's also possible in user land to emulate the semantics like webpack. If anyone is interested, there's a great article made by rspack team https://github.com/orgs/web-infra-dev/discussions/9. In terms of Vite level support, at least rolldown (voidzero)'s perspective is that preserving the exact semantics is not a goal right now as par https://rolldown.rs/guide/in-depth/tla-in-rolldown. This is not actionable without high level design, so I'll close this issue on Vitest. If anyone wants to pursue the idea, please open an issue on Vite.

---

@spaceemotion Yes, cyclic import evaluation can be somewhat unpredictable as it depends on which module is first imported as entry (which is also the case for genuine Node runtime too). Vite SSR side improvement is still just a best effort to mimic, so it's possible that some cases missed out to be handled (actually there a few more fix related to this vitejs/vite#19841). If you have a reproduction, I'm happy to take a look, so please feel free to open a separate issue.