Repository navigation
Changed
- Dev server: imports of a CommonJS dependency give what Vite 8's dev server gives (plugins/importAnalysis.ts:
transformCjsImport,interopNamedImports), where oj had shapes of its own. Each of these takes something away from an app that relied on the old shape:- The default import of a dependency flagged
__esModule, in an app whosepackage.jsonhas no"type": "module"(or in a file under such apackage.json, and in every file withlegacy.inconsistentCjsInterop).import d from "<dep>",import d, { a } from,import { default as d } fromandexport { default } fromof a transpiled package (exports.__esModule = true; exports.default = X) giveX, the package's owndefault, where oj gave the wholemodule.exports({ default: X, ... }). That is what Vite's dev server and a build (Vite's andoj build) give, soimport DatePicker from "<cjs package>"renders in dev as it does in production; code that worked around the old shape withd.default, or read a named export offd(d.a), must usedand a named import. A flagged dep with nodefaultof its own (a webpack UMD bundle) isundefinedas a default import there, as in Vite's dev server (a build givesmodule.exports): import its namespace or its names. The static default import does not change in a"type": "module"app, nor for a dep that is not flagged: it ismodule.exports. (await import("<dep>")).defaultof a dependency flagged__esModule, in a"type": "module"app (any importer whose package states atype, or an.mjs/.cjsfile). It ismodule.exports, where oj gave the package's owndefault:React.lazy(() => import("<CommonJS-only component package>"))that rendered inoj devnow fails there as it does under Vite and in a build; wrap it (.then((m) => ({ default: m.default.default }))) or import a named member. In an app withouttypeit stays the package's owndefault.export * as ns from "<dep>"of a pre-bundled CommonJS dependency:nsis the pre-bundle's ES namespace,defaultalone (which ismodule.exports), where oj built an object with the members besidedefault. A build still gives the members (Vite's own dev/build difference). Re-export the names (export { a, b } from) or import the namespace and export that.- A bare
export * from "<dep>"of a pre-bundled CommonJS dependency re-exports nothing, where oj re-exported the names it could read off the file, from a second copy of the dependency loaded beside its pre-bundle. The warning is Vite's: "Unable to interopexport * from "x"in , this may lose module exports. Please export "x" as ESM or use named exports instead, e.g.export { A, B } from "x"". - A dependency flagged for interop is imported by its pre-bundle's
defaultexport, as Vite imports it, where oj imported the pre-bundle's namespace and fell back to it. One whose pre-bundle has nodefaulttherefore fails to link ("does not provide an export named 'default'") for a default, named or namespace import, as under Vite. That is an ES module listed inoptimizeDeps.needsInteropthat has no default export (take it off the list), and a dependency whose entry has noimportorexportstatement and refers to none ofmodule,exportsandrequire(an empty file or a side-effect-only script:import "dep"still runs it,import * as x from "dep"does not link). An ES module on that list that has adefaultis read off it:import * as nsandimport()are built fromdefaultand a named import is a property ofdefault, where oj read the module's own namespace. - A Node builtin (
node:fs,path), which oj serves as an empty stub in the browser: a default, namespace or dynamic import of it gets the stub module as it is, as in Vite, where oj built{ default: {} }from it.fs.defaultand the default import are the empty object as before; the namespace now also shows the stub's own__cjs_exportsmember, so code should not enumerate a builtin's namespace. A named import (import { readFile } from "node:fs") isundefinedas before. import(`dep`)whose specifier resolves to nothing fails the module's compile ("Failed to resolve import"), asimport("dep")does and as in Vite, where the template form was left as written to fail when it ran.- A directive at the top of a module (
"use client") comes after the hoisted bindings in the module oj serves, as in the module Vite serves, so it is no longer the first statement there. Plugins see the source before this rewrite.
- The default import of a dependency flagged
- Dev server: tsconfig
verbatimModuleSyntaxis read, asoj buildand Vite already read it (Vite hands it to the TypeScript transform asonlyRemoveTypeImports). It applies to every TypeScript file the nearesttsconfig.json's project includes, create-vite'stsconfig.app.jsonamong them, where the template sets it. With ittrue: an import of a type written withouttype(import { Props } from "./types") is kept and fails to link in the browser ("does not provide an export named 'Props'"), as under Vite and astscreports it (TS1484), where oj removed it; an unused value import is kept, so its module loads and runs;import { type T } from "m"still loadsm;import typeis removed. An app without the option sees no change. An edit to atsconfig.jsonis picked up while the server runs; one to a referencedtsconfig.app.jsonneeds a restart, as in Vite. The deprecatedpreserveValueImportsandimportsNotUsedAsValues, and the Vite config'soxc.typescript.onlyRemoveTypeImports, are not read in dev.
Fixed
-
Dev server:
import * as ns from "<dep>"of any CommonJS dependency has the dependency's runtime exports. A CommonJS dep's pre-bundle exports a lonedefault(itsmodule.exports), and oj boundnsto that ES namespace:import * as _ from "lodash"gave only_.default, and with a webpack UMD bundle (pdf.js 3'sbuild/pdf.js, phaser'sdist/phaser.js)ns.GlobalWorkerOptionswasundefined, sons.GlobalWorkerOptions.workerSrc = "..."threw before the app rendered. Vite's import analysis binds the namespace to{ ...module.exports, default: module.exports }(interopHelper), and oj now does the same:ns.Xis the same object as the default import'sX. With it:- A
module.exportsflagged__esModuleis treated by how Node reads the importing file. For an importer that is an ES module (an.mjsor.mtsfile, or one under a nearestpackage.jsonwith"type": "module"; Vite'sisFilePathESM) it is spread besidedefaultlike any other; for any other importer it is the namespace as it is.await import("<dep>")follows the same rule by Vite'sisFilePathFormatExplicit(an importer under"type": "commonjs"or in a.cjsfile counts too). The object a dynamic import gives is an ordinary one where it had a null prototype, and an array-valuedmodule.exportscontributes onlydefault. legacy.inconsistentCjsInterop: trueis read, by the dev server and byoj build: no importer is then an ES module for these rules, as in Vite.oj buildignored it and gavemodule.exportsas the default import of a flagged dep wherevite buildgave the dep's owndefault. An app build's worker bundles read it too; a library or SSR build's worker bundle is not given the app's config.- The nearest
package.jsonis looked up on each request of the importer (onestatper directory up to it, the file read again only when its modification time or size moved), so one created, deleted or given anothertypewhile the server runs decides the importer's next response. Vite's watcher drops a changed or deletedpackage.jsonfrom its package cache; oj also notices a created one. - The bindings are hoisted to the start of the file, where Vite puts them, so a function declared in the module and called above the import statement finds them initialised, where it threw
Cannot access 'ns' before initialization. They follow a hashbang line. oj's JSX transform runs after this rewrite, where Vite's runs before it, and reads a file's JSX pragmas (/** @jsxImportSource x */,@jsx,@jsxFrag,@jsxRuntime) from the comments before its first statement, so the pragmas those comments hold are restated in one comment ahead of the bindings; they are read as oxc reads them (every pragma of every such comment, the last of a kind). A multi-line import declaration orimport()keeps its line breaks and the helper adds no line, so every line keeps its number and the module's source map points at the right lines; oj collapsed such an import to one line and put the helper on a line of its own. A module whose first statement is decorated (@dec export class X {}) is no longer broken by the inserted text. - In a TypeScript module without
verbatimModuleSyntax, an import binding no value refers to (import { Props } from "<dep>"withPropsused only as a type, an inlinetypespecifier, an unused import) gets no read from this rewrite, as the TypeScript transform that runs next removes it, and a declaration with no binding left is left for that transform to remove: Vite's import analysis runs after that transform and never sees one. A types-only package whose entry is an empty file is imported that way and has nodefaultto import. An import the JSX transform refers to is kept as that transform's TypeScript pass keeps it: the classic factory and fragment from the config (esbuild.jsxFactory,oxc.jsx.pragma) or a@jsxcomment, andReactbeside JSX. An import redeclared as a value in the module (import { Status } from "<dep>"; const Status = ..., where the import is only a type) is removed as that pass removes it, where the rewrite declaredStatustwice and the module failed to compile. import(`dep`)with a template literal that has no substitution is read asimport("dep"), as in Vite; oj left the specifier as it was, which the browser cannot resolve.- A CommonJS dependency served file by file that parses only as a script (sloppy-mode code, such as
awaitused as a name) is still read as CommonJS; one that parses neither as a module nor as a script (JSX in a.jsfile) is not taken for CommonJS. - The helper names no global, so a module with a top-level binding called
ObjectorArray(import { Array } from "effect") is safe. - A dep served file by file (
optimizeDeps.exclude) follows the same rules: from an ES-module importer thedefaultof its namespace ismodule.exports, andexport * as ns fromit is built the same way, without oj's own__cjs_exportsmember.
Not matched: the TanStack Start bundles do not read
legacy.inconsistentCjsInterop; a dependency served file by file has no counterpart in Vite (which does not serve a CommonJS file to the browser), so a bareexport * fromit still re-exports the names oj can read; a namespace import of a Node builtin's stub has oj's__cjs_exportsmember besidedefault, which a wrapped CommonJS file'srequireof the builtin reads; and a named import of a builtin isundefined, where Vite's stub throws when the importing module loads ("has been externalized for browser compatibility"). - A
-
TanStack Start dev: the server render's namespace of an external CommonJS dependency has the names Node gives it. A webpack UMD bundle (pdf.js 3's
build/pdf.js) assigns each export in an inner module (exports.GlobalWorkerOptions = ...) and defines it again on its entry with the descriptor in parentheses (Object.defineProperty(exports, "GlobalWorkerOptions", ({ enumerable: true, get: function () { ... } }))). The engine's export analysis, which follows cjs-module-lexer, takes such adefinePropertyfor a getter it cannot vouch for and removes the name, soimport * as pdfjsLib from "pdfjs-dist"had 117 names on the server, every one but the 44 the package really exports:pdfjsLib.GlobalWorkerOptions.workerSrc = "..."at the top of a route module threw, andimport { GlobalWorkerOptions } from "pdfjs-dist"failed to link ("does not provide an export named"). Node did the same while it used cjs-module-lexer (1.4.3 reads 115 names off that file); the lexer current Node releases use (merve, in Node 24.17) only declines to add a name for such a call and keeps one another statement exports, and the engine presents itself as a current Node (process.versionis v26); Vite's module runner imports an external natively, so its server render has Node's namespace. The ES wrapper of a CommonJS file now also exports each name the file both assigns (exports.name = ...) and defines withObject.defineProperty(exports, "name", ...): 161 names for pdf.js, the same list as Node 24.17 and Vite'sssrLoadModuleon it. A name the file only defines that way, or one a file it re-exports from drops, is still not added. A Start build bundles the dependency and was not affected.