Skip to content

oj v0.4.17

Latest

Choose a tag to compare

@github-actions github-actions released this 18 Nov 20:06
· 4 commits to main since this release
737f32a

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 whose package.json has no "type": "module" (or in a file under such a package.json, and in every file with legacy.inconsistentCjsInterop). import d from "<dep>", import d, { a } from, import { default as d } from and export { default } from of a transpiled package (exports.__esModule = true; exports.default = X) give X, the package's own default, where oj gave the whole module.exports ({ default: X, ... }). That is what Vite's dev server and a build (Vite's and oj build) give, so import DatePicker from "<cjs package>" renders in dev as it does in production; code that worked around the old shape with d.default, or read a named export off d (d.a), must use d and a named import. A flagged dep with no default of its own (a webpack UMD bundle) is undefined as a default import there, as in Vite's dev server (a build gives module.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 is module.exports.
    • (await import("<dep>")).default of a dependency flagged __esModule, in a "type": "module" app (any importer whose package states a type, or an .mjs/.cjs file). It is module.exports, where oj gave the package's own default: React.lazy(() => import("<CommonJS-only component package>")) that rendered in oj dev now 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 without type it stays the package's own default.
    • export * as ns from "<dep>" of a pre-bundled CommonJS dependency: ns is the pre-bundle's ES namespace, default alone (which is module.exports), where oj built an object with the members beside default. 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 interop export * 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 default export, as Vite imports it, where oj imported the pre-bundle's namespace and fell back to it. One whose pre-bundle has no default therefore 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 in optimizeDeps.needsInterop that has no default export (take it off the list), and a dependency whose entry has no import or export statement and refers to none of module, exports and require (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 a default is read off it: import * as ns and import() are built from default and a named import is a property of default, 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.default and the default import are the empty object as before; the namespace now also shows the stub's own __cjs_exports member, so code should not enumerate a builtin's namespace. A named import (import { readFile } from "node:fs") is undefined as before.
    • import(`dep`) whose specifier resolves to nothing fails the module's compile ("Failed to resolve import"), as import("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.
  • Dev server: tsconfig verbatimModuleSyntax is read, as oj build and Vite already read it (Vite hands it to the TypeScript transform as onlyRemoveTypeImports). It applies to every TypeScript file the nearest tsconfig.json's project includes, create-vite's tsconfig.app.json among them, where the template sets it. With it true: an import of a type written without type (import { Props } from "./types") is kept and fails to link in the browser ("does not provide an export named 'Props'"), as under Vite and as tsc reports it (TS1484), where oj removed it; an unused value import is kept, so its module loads and runs; import { type T } from "m" still loads m; import type is removed. An app without the option sees no change. An edit to a tsconfig.json is picked up while the server runs; one to a referenced tsconfig.app.json needs a restart, as in Vite. The deprecated preserveValueImports and importsNotUsedAsValues, and the Vite config's oxc.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 lone default (its module.exports), and oj bound ns to that ES namespace: import * as _ from "lodash" gave only _.default, and with a webpack UMD bundle (pdf.js 3's build/pdf.js, phaser's dist/phaser.js) ns.GlobalWorkerOptions was undefined, so ns.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.X is the same object as the default import's X. With it:

    • A module.exports flagged __esModule is treated by how Node reads the importing file. For an importer that is an ES module (an .mjs or .mts file, or one under a nearest package.json with "type": "module"; Vite's isFilePathESM) it is spread beside default like any other; for any other importer it is the namespace as it is. await import("<dep>") follows the same rule by Vite's isFilePathFormatExplicit (an importer under "type": "commonjs" or in a .cjs file counts too). The object a dynamic import gives is an ordinary one where it had a null prototype, and an array-valued module.exports contributes only default.
    • legacy.inconsistentCjsInterop: true is read, by the dev server and by oj build: no importer is then an ES module for these rules, as in Vite. oj build ignored it and gave module.exports as the default import of a flagged dep where vite build gave the dep's own default. 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.json is looked up on each request of the importer (one stat per directory up to it, the file read again only when its modification time or size moved), so one created, deleted or given another type while the server runs decides the importer's next response. Vite's watcher drops a changed or deleted package.json from 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 or import() 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>" with Props used only as a type, an inline type specifier, 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 no default to 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 @jsx comment, and React beside 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 declared Status twice and the module failed to compile.
    • import(`dep`) with a template literal that has no substitution is read as import("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 await used as a name) is still read as CommonJS; one that parses neither as a module nor as a script (JSX in a .js file) is not taken for CommonJS.
    • The helper names no global, so a module with a top-level binding called Object or Array (import { Array } from "effect") is safe.
    • A dep served file by file (optimizeDeps.exclude) follows the same rules: from an ES-module importer the default of its namespace is module.exports, and export * as ns from it is built the same way, without oj's own __cjs_exports member.

    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 bare export * from it still re-exports the names oj can read; a namespace import of a Node builtin's stub has oj's __cjs_exports member beside default, which a wrapped CommonJS file's require of the builtin reads; and a named import of a builtin is undefined, where Vite's stub throws when the importing module loads ("has been externalized for browser compatibility").

  • 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 a defineProperty for a getter it cannot vouch for and removes the name, so import * 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, and import { 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.version is 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 with Object.defineProperty(exports, "name", ...): 161 names for pdf.js, the same list as Node 24.17 and Vite's ssrLoadModule on 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.