chore: v27 migration to ESM-only package (BREAKING) by mmaietta · Pull Request #9544 · electron-userland/electron-builder

mmaietta · 2026-01-28T08:39:29Z

Resolves #9483!!

Summary

Migrates the build from tsc --build to tsup so every publishable package ships dual CJS + ESM with type declarations, and updates the test/tooling pipeline to match.

Compiler & packaging

Replaces tsc --build with tsup for all 8 publishable packages, producing CJS (.js), ESM (.mjs), and declarations (.d.ts / .d.mts) in dist/.
Conditional exports on every package (require → CJS, import → ESM, types → declarations) plus a dev-only ./src/* subpath so the monorepo's tests can import un-bundled source.
indexInternal.ts (./internal) entry per package for cross-package internal API access, replacing deep pkg/out/... paths.
Removes "type": "module" from electron-updater in favour of conditional exports.
New packages/tsconfig-tsup.json (no composite) used only by tsup's DTS worker to avoid TS6307.
tsconfig-base.json retargeted to ESNext + moduleResolution: "bundler", useDefineForClassFields: false (preserves pre-ES2022 class-field semantics).

Toolchain

ts-node → tsx for the vitest runner scripts (works with bundler resolution, no extra flags).
compile now runs pnpm -r ... build (per-package tsup) instead of tsc --build; typecheck retains tsc --build for whole-graph type validation.

Source fixes surfaced by the stricter ESM pipeline

Broke a real circular dependency: platformPackager.ts imported the ./index barrel (→ linuxPackager → extends PlatformPackager), which fails under ESM eager class-init. Made the barrel import type-only, sourced Platform from ./core, and replaced this instanceof LinuxPackager with a value-free "executableName" in this check.
Fixed stale imports left by the in-progress ESM migration: deepAssign.ts (./mapper → builder-util-runtime), AppImageTarget.ts (deleted ./util/appBuilder → inline + builder-util-runtime#objectToArgs).
rollup-plugin-dts incompatibilities: import X = NS.Y namespace aliases → type X = NS.Y (builder-util/log.ts, electron-updater/{AppUpdater,MacUpdater,electronHttpExecutor}.ts).
import.meta.dirname (Node 21.2+ ESM-only) → bundle-safe __dirname + shims: true (app-builder-lib pathManager/rebuild/packageMetadata).
Misc: tar internal type path → public tar, readline/promises → node:readline/promises, yargs cast in builder.ts/install-app-deps.ts.

Test infrastructure

vitest resolves workspace packages to source via resolve.alias in run-vitest.ts (each pkg / pkg/internal → its src/*.ts). Tests run against un-bundled source so vite handles CJS interop (e.g. fs-extra) and circular deps, and vi.mock can intercept individual modules.
Migrated all test deep-imports pkg/out/... → pkg/src/...; cliTest mocks consolidated onto app-builder-lib/internal.
estree-walker@3.0.3 patch adds a require export condition (one-line patch) so tsx/Node 22 can load it via vitest's mocker.
test/tsconfig.json drops package project-references (resolves through exports instead, avoiding mixed out/↔dist/ type identities).

Script/config fixes

scripts/checkDeps.js: ignore dist/, skip the dynamically-imported @electron/universal and root-only tsup/tsx/is-ci/vitest.
eslint.config.mjs: ignore **/dist and **/tsup.config.ts; disable the curly/nonblock-statement-body-position conflict; relax require-await/unbound-method for test/src.
Root tsconfig.json no longer references test/website (built separately).

… `env: { COREPACK_ENABLE_STRICT: "0", ...process.env },` to allow `npm list` to work across environments. extract fallback node collector (Traversal) to separate class due to differing parsing logic from NPM collector

# Conflicts: # packages/app-builder-lib/package.json # packages/dmg-builder/package.json # packages/electron-builder-squirrel-windows/package.json # packages/electron-builder/package.json

…m-migration # Conflicts: # packages/app-builder-lib/src/node-module-collector/bunNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/nodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/npmNodeModulesCollector.ts # packages/app-builder-lib/src/util/appFileCopier.ts

# Conflicts: # packages/app-builder-lib/package.json # packages/app-builder-lib/src/asar/asarUtil.ts # packages/app-builder-lib/src/binDownload.ts # packages/app-builder-lib/src/node-module-collector/bunNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/index.ts # packages/app-builder-lib/src/node-module-collector/moduleCache.ts # packages/app-builder-lib/src/node-module-collector/nodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/npmNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/pnpmNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/traversalNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/types.ts # packages/app-builder-lib/src/node-module-collector/yarnBerryNodeModulesCollector.ts # packages/app-builder-lib/src/node-module-collector/yarnNodeModulesCollector.ts # packages/app-builder-lib/src/publish/PublishManager.ts # packages/app-builder-lib/src/targets/FlatpakTarget.ts # packages/app-builder-lib/src/targets/archive.ts # packages/app-builder-lib/src/util/appFileCopier.ts # packages/dmg-builder/package.json # packages/dmg-builder/src/dmgUtil.ts # packages/electron-builder-squirrel-windows/package.json # packages/electron-builder/package.json # packages/electron-publish/package.json # packages/electron-updater/src/differentialDownloader/DataSplitter.ts # pnpm-lock.yaml # test/src/helpers/packTester.ts # test/src/updater/blackboxUpdateTest.ts # test/src/updater/differentialUpdateTest.ts

changeset-bot · 2026-01-28T08:39:33Z

🦋 Changeset detected

Latest commit: 3f03227

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

socket-security · 2026-01-28T08:40:00Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@tsconfig/node22@22.0.5
	tsx@4.22.3
	fs-extra@11.3.5

View full report

…ractions

…ng the traditional `.` root export

…m-migration # Conflicts: # packages/app-builder-lib/src/util/yarn.ts # test/src/HoistedNodeModuleTest.ts

# Conflicts: # test/src/helpers/updaterTestUtil.ts

# Conflicts: # package.json # packages/app-builder-lib/helpers/dynamic-import.js # packages/app-builder-lib/package.json # packages/app-builder-lib/src/asar/asarFileChecker.ts # packages/app-builder-lib/src/asar/asarUtil.ts # packages/app-builder-lib/src/binDownload.ts # packages/app-builder-lib/src/codeSign/codesign.ts # packages/app-builder-lib/src/codeSign/macCodeSign.ts # packages/app-builder-lib/src/codeSign/windowsSignToolManager.ts # packages/app-builder-lib/src/configuration.ts # packages/app-builder-lib/src/electron/ElectronFramework.ts # packages/app-builder-lib/src/electron/injectFFMPEG.ts # packages/app-builder-lib/src/fileTransformer.ts # packages/app-builder-lib/src/index.ts # packages/app-builder-lib/src/linuxPackager.ts # packages/app-builder-lib/src/macPackager.ts # packages/app-builder-lib/src/node-module-collector/pnpmNodeModulesCollector.ts # packages/app-builder-lib/src/options/SnapOptions.ts # packages/app-builder-lib/src/packager.ts # packages/app-builder-lib/src/platformPackager.ts # packages/app-builder-lib/src/targets/AppxTarget.ts # packages/app-builder-lib/src/targets/FlatpakTarget.ts # packages/app-builder-lib/src/targets/FpmTarget.ts # packages/app-builder-lib/src/targets/LinuxTargetHelper.ts # packages/app-builder-lib/src/targets/MsiTarget.ts # packages/app-builder-lib/src/targets/appimage/AppImageTarget.ts # packages/app-builder-lib/src/targets/appimage/appImageUtil.ts # packages/app-builder-lib/src/targets/archive.ts # packages/app-builder-lib/src/targets/differentialUpdateInfoBuilder.ts # packages/app-builder-lib/src/targets/nsis/NsisTarget.ts # packages/app-builder-lib/src/targets/nsis/nsisUtil.ts # packages/app-builder-lib/src/targets/snap.ts # packages/app-builder-lib/src/toolsets/linux.ts # packages/app-builder-lib/src/toolsets/windows.ts # packages/app-builder-lib/src/util/config/config.ts # packages/app-builder-lib/src/util/packageDependencies.ts # packages/app-builder-lib/src/util/resolve.ts # packages/app-builder-lib/src/util/yarn.ts # packages/app-builder-lib/src/winPackager.ts # packages/builder-util-runtime/package.json # packages/builder-util-runtime/src/index.ts # packages/builder-util/package.json # packages/builder-util/src/DebugLogger.ts # packages/builder-util/src/deepAssign.ts # packages/builder-util/src/util.ts # packages/dmg-builder/package.json # packages/dmg-builder/src/dmg.ts # packages/dmg-builder/src/dmgLicense.ts # packages/dmg-builder/src/dmgUtil.ts # packages/dmg-builder/src/licenseButtons.ts # packages/electron-builder-squirrel-windows/package.json # packages/electron-builder-squirrel-windows/src/SquirrelWindowsTarget.ts # packages/electron-builder/package.json # packages/electron-builder/src/builder.ts # packages/electron-builder/src/cli/cli.ts # packages/electron-builder/src/cli/install-app-deps.ts # packages/electron-publish/package.json # packages/electron-publish/src/index.ts # packages/electron-publish/src/s3/baseS3Publisher.ts # packages/electron-publish/src/s3/s3Publisher.ts # packages/electron-publish/src/s3/spacesPublisher.ts # packages/electron-publish/src/snapStorePublisher.ts # packages/electron-updater/src/BaseUpdater.ts # pnpm-lock.yaml # scripts/fix-schema.js # scripts/renderer/src/typedoc2html.ts # test/package.json # test/snapshots/updater/blackboxUpdateTest.js.snap # test/src/ExtraBuildResourcesTest.ts # test/src/HoistedNodeModuleTest.ts # test/src/binDownloadTest.ts # test/src/helpers/downloadElectron.ts # test/src/helpers/launchAppCrossPlatform.ts # test/src/helpers/packTester.ts # test/src/linux/debTest.ts # test/src/linux/linuxPackagerTest.ts # test/src/linux/snapHeavyTest.ts # test/src/mac/macPackagerTest.ts # test/src/rebuilderTest.ts # test/src/updater/blackboxUpdateTest.ts # test/src/updater/differentialUpdateTest.ts # test/src/updater/linuxUpdaterTest.ts # test/src/windows/appxTest.ts # test/src/windows/assistedInstallerTest.ts # test/src/windows/msiTest.ts # test/src/windows/msiWrappedTest.ts # test/src/windows/portableTest.ts # test/src/windows/squirrelWindowsTest.ts # test/src/windows/webInstallerTest.ts # test/src/windows/winCodeSignTest.ts # test/src/windows/winPackagerTest.ts # test/tsconfig.json # test/vitest-scripts/cache.ts # test/vitest-scripts/file-discovery.ts # test/vitest-scripts/run-vitest.ts # test/vitest-scripts/smart-config.ts # test/vitest-scripts/smart-shard-count.ts # test/vitest-scripts/vitest-smart-sequencer.ts

mmaietta added 15 commits December 9, 2025 08:23

updating all engines to node 22

80a4ba3

tmp save for .js extension migration

5a5d2b7

tmp save

d26567f

tmp save for .js extension migration

c92b222

tmp save

c951258

Merge branch 'master' into chore/esm-migration

5ad186e

# Conflicts: # packages/app-builder-lib/package.json # packages/dmg-builder/package.json # packages/electron-builder-squirrel-windows/package.json # packages/electron-builder/package.json

tmp save

1235446

got it all compiling

fa1ceb2

esm complete on tests as well?

fb7cff6

tests run

c978ab4

it builds

f315958

cleanup

87d5cf7

github-actions Bot added windows mac linux Squirrel.Windows nsis AppImage electron-updater snap app-builder-lib electron-publish builder-util dmg-builder labels Jan 28, 2026

tmp save

37c7b37

mmaietta added 3 commits May 1, 2026 07:58

add retry to blackbox update test due to flakiness of e2e system inte…

5641a26

…ractions

add fuses to blackbox update test

6f2b0b7

revert hoisted snapshot changes to see if we can reduce PR diff size

3b38b0e

mmaietta force-pushed the chore/esm-migration branch from 52191a7 to 3b38b0e Compare May 2, 2026 15:51

mmaietta added 4 commits May 2, 2026 16:32

initial migration/creation of /internal package export for minimizi…

01b91f6

…ng the traditional `.` root export

yesssss

1b4dbdc

Merge commit '99676722552714a97c2285b170230ef941d411c0' into chore/es…

18fdf69

…m-migration # Conflicts: # packages/app-builder-lib/src/util/yarn.ts # test/src/HoistedNodeModuleTest.ts

optimize dependencies/devDependencies list

e27a88a

mmaietta changed the base branch from release/v27 to master May 3, 2026 00:18

mmaietta added 2 commits May 2, 2026 17:56

fix all circular references

76a42c1

fix import

e9f6762

mmaietta changed the title ~~chore: v27 migration to ESM [WIP] (BREAKING)~~ chore: v27 migration to ESM-only package (BREAKING) May 4, 2026

mmaietta added 2 commits May 5, 2026 12:50

Merge branch 'master' into chore/esm-migration

634b1e4

# Conflicts: # test/src/helpers/updaterTestUtil.ts

address imports

b47b8bc

mmaietta marked this pull request as ready for review May 6, 2026 14:48

prettier

3ba131a

skmedix reviewed May 8, 2026

View reviewed changes

Comment thread packages/app-builder-lib/src/targets/AppImageTarget.ts Outdated

Comment thread packages/electron-updater/package.json Outdated

Comment thread packages/app-builder-lib/package.json Outdated

mmaietta mentioned this pull request Jun 3, 2026

pnpm cannot import @electron/osx-sign/dist/cjs/util-identities #9816

Closed

mmaietta added 5 commits June 3, 2026 05:40

initial introduction of tsup

cf5340b

tsupppppp?

0cf1192

tmp save

c8d40be

regen lockfile

cac6d48

github-advanced-security AI found potential problems Jun 3, 2026

View reviewed changes

Comment thread test/vitest-scripts/run-vitest.ts Fixed

mmaietta added 6 commits June 3, 2026 08:28

update engines to 22.12

5b5709c

retry with proper export/imports

b2c25fc

just get it working

ba20c7b

use /internal import instead of deep imports

53d8ac2

swap back to tsc instead of tsup

b0497fc

update fs-extra to ESM-supported version

3f03227

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: v27 migration to ESM-only package (BREAKING)#9544

chore: v27 migration to ESM-only package (BREAKING)#9544
mmaietta wants to merge 77 commits into
masterfrom
chore/esm-migration

mmaietta commented Jan 28, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

mmaietta commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

changeset-bot Bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

socket-security Bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mmaietta commented Jan 28, 2026 •

edited

Loading

changeset-bot Bot commented Jan 28, 2026 •

edited

Loading

socket-security Bot commented Jan 28, 2026 •

edited

Loading