Skip to content

TypeScript import X = Default.Y silently drops the default import when bundling → ReferenceError at runtime #4507

Closed
Ditto190/esbuild-modme
#4

Description

@alexciesielski

Summary

When a module contains a TypeScript import-equals alias whose base is a default import (import X = Base.Y), esbuild's bundler drops the import Base from '...' statement entirely — while leaving value references to Base in the output. The result is a free identifier and a ReferenceError at runtime.

There is no warning and no error; the build exits 0.

Version

esbuild 0.28.1 (current latest at time of writing).

Minimal reproduction

Two files, no config, no package.json needed.

dep.js

export default class Base {
  static hello() { return 'dep code is present'; }
}

entry.ts

import Base from './dep.js';
import Alias = Base.SomeType;

export function make() {
  return new Base();
}
$ esbuild entry.ts --bundle --format=esm

Actual output

// entry.ts
function make() {
  return new Base();
}
export {
  make
};

The import is gone, dep.js is not included in the bundle at all, and Base is left as an unbound free identifier. Running it:

return new Base();
       ^
ReferenceError: Base is not defined

Exit code is 0. result.warnings and result.errors are both empty.

Expected

Either the import is preserved (since Base is used as a value in new Base()), or the build fails / warns. Silently emitting a reference to an undefined variable seems clearly wrong.

For comparison, tsc preserves the import here — it knows Alias is type-only, erases just that declaration, and keeps import Base from './dep.js'.

Notes from narrowing it down

A few things that might help locate it:

  • The alias does not need to be used. Deleting the Alias reference everywhere else still reproduces; the mere presence of the import Alias = Base.SomeType; line is enough. Removing that one line fixes it.
  • Only bundle: true is affected. esbuild.transform() with loader: 'ts', and esbuild.build() with bundle: false, both correctly keep import Base from './dep.js'.
  • Only a default import base is affected. A named or namespace base is fine, even with genuine runtime use:
    import { ns } from './dep.js';
    import Alias = ns.SomeType;
    export const k = ns.someEnum.Member;   // works, ns import preserved
  • sideEffects is irrelevant — reproduces with "sideEffects": false, without it, and with no package.json at all.
  • The dependency is resolved and read — it shows up in metafile.inputs — it just contributes nothing to the output.
  • If the aliased path happens to exist as a real runtime value (e.g. the dep also has a merged export namespace Base { ... } emitting an object), it does not reproduce. So it seems related to resolving Base.SomeType against the module's actual exports and concluding the whole binding is type-only.
  • Possibly adjacent: import-is-undefined warning issued on TS import equals declaration #3271 covers the import-is-undefined warning for an import-equals whose base is a local namespace. This case is different — the base is an imported default, and no warning fires at all.

Impact

This shipped a ReferenceError to production for us. The pattern is easy to write and looks harmless, tsc type-checks it fine, and nothing in the build output hints at a problem. The giveaway in a minified bundle is that the identifier stays unminified — esbuild won't rename what it treats as a global — which is a fairly subtle thing to notice.

Activity

  1. added a commit that references this issue on Aug 8, 2026
    07f6e8c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions