Skip to content

feat: support new Worker() instantiation in universal targets#21195

Merged
alexander-akait merged 16 commits into
mainfrom
feat/universal-worker-instantiation
Jun 17, 2026
Merged

feat: support new Worker() instantiation in universal targets#21195
alexander-akait merged 16 commits into
mainfrom
feat/universal-worker-instantiation

Conversation

@alexander-akait

Copy link
Copy Markdown
Member

Summary

In a universal (["node", "web"] + output.module) target a global new Worker(new URL(...)) crashed in node because there is no global Worker. This resolves the constructor through a runtime helper that uses the global Worker on the web and worker_threads.Worker (via process.getBuiltinModule) in node, only for universal targets. The defensive node-builtin getter introduced for universal node-commonjs externals (#21187) is unified into RuntimeTemplate.getBuiltinModule and reused here so the logic lives in one place.

What kind of change does this PR introduce?

feat (plus a small refactor unifying the node-builtin getter).

Did you add tests for your changes?

Yes — test/configCases/worker/universal now actually instantiates the worker under node (it was a no-op there before); the existing externals cases cover the shared helper.

Does this PR introduce a breaking change?

No — pure web and pure node builds are unchanged; the rewrite only applies to universal targets.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

n/a — the workers documentation could note that new Worker(new URL(...)) now works under a universal target (constructor only; the messaging API still differs between worker_threads and web Workers).

Use of AI

Yes — the implementation, tests and this description were produced with Claude Code (Anthropic) and reviewed before submission.


Generated by Claude Code

In a universal (node + web) target, a global `new Worker(new URL(...))`
crashed in node because there is no global `Worker`. Resolve the constructor
through a runtime helper that uses the global `Worker` on the web and
`worker_threads.Worker` (via `process.getBuiltinModule`) in node, only when
the target is universal.
…orker

Both the universal node-commonjs external loader and the universal worker
constructor obtained a node builtin via `process.getBuiltinModule`, guarded for
the browser and old node. Extract that into `RuntimeTemplate.getBuiltinModule`
and use it in both, so the universal node-builtin access lives in one place.
@changeset-bot

changeset-bot Bot commented Jun 16, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0720271

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

This PR includes changesets to release 1 package
Name Type
webpack Minor

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

@github-actions

github-actions Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

This PR is packaged and the instant preview is available (80f5ed8).

Install it locally:

  • npm
npm i -D webpack@https://pkg.pr.new/webpack@80f5ed8
  • yarn
yarn add -D webpack@https://pkg.pr.new/webpack@80f5ed8
  • pnpm
pnpm add -D webpack@https://pkg.pr.new/webpack@80f5ed8

@codecov

codecov Bot commented Jun 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.70%. Comparing base (7552543) to head (0720271).

Additional details and impacted files
@@           Coverage Diff           @@
##             main   #21195   +/-   ##
=======================================
  Coverage   92.70%   92.70%           
=======================================
  Files         588      589    +1     
  Lines       64144    64180   +36     
  Branches    17791    17802   +11     
=======================================
+ Hits        59464    59500   +36     
  Misses       4680     4680           
Flag Coverage Δ
css-parsing 28.70% <19.51%> (-0.01%) ⬇️
html5lib 31.17% <19.51%> (-0.01%) ⬇️
integration 88.68% <100.00%> (+<0.01%) ⬆️
test262 45.52% <23.25%> (-0.02%) ⬇️
unit 41.03% <27.90%> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The universal worker resolves `worker_threads.Worker` via
`process.getBuiltinModule`, available only in Node >= 22.3. On older Node the
bundle still loads (the helper is falsy-guarded) but the worker cannot be
instantiated, so skip the case there instead of failing.
@codspeed-hq

codspeed-hq Bot commented Jun 16, 2026

Copy link
Copy Markdown

Merging this PR will degrade performance by 51.39%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
❌ 2 regressed benchmarks
✅ 123 untouched benchmarks
⏩ 18 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Memory benchmark "lodash", scenario '{"name":"mode-development-rebuild","mode":"development","watch":true}' 126.3 KB 859.1 KB -85.3%
Memory benchmark "side-effects-reexport", scenario '{"name":"mode-development-rebuild","mode":"development","watch":true}' 768.9 KB 1,198.8 KB -35.86%
Memory benchmark "css-modules", scenario '{"name":"mode-production","mode":"production"}' 9 MB 7.4 MB +21.78%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing feat/universal-worker-instantiation (0720271) with main (7552543)

Open in CodSpeed

Footnotes

  1. 18 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

alexander-akait and others added 13 commits June 16, 2026 19:29
…ility

Derive `output.environment.nodeBuiltinModuleGetter` from the target node
version (`process.getBuiltinModule()` is Node >= 22.3). The shared
`RuntimeTemplate.getBuiltinModule` now calls the API directly when it is
known-supported, and otherwise tries it and falls back to `createRequire`
inside `try/catch` so a non-node or old-node load never throws. Applies to
both the universal node-commonjs external and the universal worker.
Consume a node builtin through the generated getter in the `.mjs` (ESM)
output and assert a working runtime value, proving the createRequire/
getBuiltinModule getter runs in a real ECMAScript module. Also refreshes
the CLI args and browserslist environment snapshots for the new
`nodeBuiltinModuleGetter` capability.
…r fallback

Replace the IIFE + double try/catch with a single `typeof`-guarded
ternary: prefer `process.getBuiltinModule()`, else `createRequire` when
`require` exists. `typeof` never throws on undeclared names, so the
expression stays safe in the browser and in ESM (where `require` is
absent) while shrinking the generated code.
`require` doesn't exist in ESM and universal output is always ESM, so the
createRequire-via-require fallback could never run there. The fallback now
just probes `process.getBuiltinModule` with `typeof` and calls it; the
createRequire access for node-commonjs externals is built on that getter,
so no `require` is referenced.
…catch

Probe process.getBuiltinModule at runtime and use it when present; otherwise
load via require()/createRequire wrapped in try/catch so the ReferenceError it
throws in ESM (and the browser) is swallowed. Supports old and new Node in
ECMAScript module output.
…e guard

Universal output is ESM, where require doesn't exist, so the require/createRequire
fallback could never run. Use the same process.getBuiltinModule typeof guard the
universal node-commonjs externals loader uses; node <22.3 in ESM stays falsy (no
synchronous builtin access is possible there).
Replace the inline externalsPresets.node && web destructure in the worker and
node-commonjs externals with a named RuntimeTemplate helper. platform flags are
null for a universal target, so externals presets remain the source of truth;
the helper makes that intent explicit and shared.
Match the existing isUniversalTarget determination in WebpackOptionsApply
(output.module + null node/web platform flags) instead of externals presets,
and use a target-neutral name that extends to future target combinations. Shared
by the worker rewrite and the node-commonjs externals loader.
@github-actions

Copy link
Copy Markdown
Contributor

Types Coverage

Coverage after merging feat/universal-worker-instantiation into main will be
99.34%
Coverage Report
FileStmtsBranchesFuncsLinesUncovered Lines
bin
   webpack.js98.77%100%100%98.77%91
examples
   build-common.js100%100%100%100%
   buildAll.js100%100%100%100%
   examples.js100%100%100%100%
   template-common.js98.21%100%100%98.21%72
examples/custom-javascript-parser
   test.filter.js100%100%100%100%
examples/custom-javascript-parser/internals
   acorn-parse.js100%100%100%100%
   meriyah-parse.js100%100%100%100%
   oxc-parse.js91.30%100%100%91.30%140, 142–143, 145, 147, 153–154, 161, 168, 90
examples/markdown
   webpack.config.mjs100%100%100%100%
examples/typescript
   test.filter.js100%100%100%100%
examples/typescript-non-erasable
   test.filter.js50%100%100%50%5
examples/virtual-modules
   test.filter.js100%100%100%100%
examples/wasm-bindgen-esm
   test.filter.js100%100%100%100%
examples/wasm-complex
   test.filter.js100%100%100%100%
examples/wasm-simple
   test.filter.js100%100%100%100%
examples/wasm-simple-source-phase
   test.filter.js100%100%100%100%
lib
   APIPlugin.js100%100%100%100%
   AsyncDependenciesBlock.js100%100%100%100%
   AutomaticPrefetchPlugin.js100%100%100%100%
   BannerPlugin.js100%100%100%100%
   Cache.js98.21%100%100%98.21%101
   CacheFacade.js100%100%100%100%
   Chunk.js99.72%100%100%99.72%39
   ChunkGraph.js100%100%100%100%
   ChunkGroup.js100%100%100%100%
   ChunkTemplate.js100%100%100%100%
   CleanPlugin.js99.15%100%100%99.15%206, 226
   CodeGenerationResults.js100%100%100%100%
   CompatibilityPlugin.js100%100%100%100%
   Compilation.js98.44%100%100%98.44%1609, 1905, 1912, 1920, 1942, 2838, 3317–3318, 3350, 4014, 4044, 4097–4098, 4102, 4107, 4123–4124, 4138–4139, 4144–4145, 4622, 4648, 513, 518, 5456, 5488, 5505, 5521, 5537, 5552, 5577–5578, 5580, 5908, 5913, 5919, 5922, 5934, 5936, 5940, 5956, 5971, 6003, 6057, 6081, 6195, 763–764
   Compiler.js99.56%100%100%99.56%1135–1136, 1144
   ConcatenationScope.js98.59%100%100%98.59%189
   ConditionalInitFragment.js100%100%100%100%
   ConstPlugin.js100%100%100%100%
   ContextExclusionPlugin.js100%100%100%100%
   ContextModule.js100%100%100%100%
   ContextModuleFactory.js97.40%100%100%97.40%258, 395, 418, 420, 424, 433–434
   ContextReplacementPlugin.js100%100%100%100%
   DefinePlugin.js99%100%100%99%171–172, 188, 207, 281
   DependenciesBlock.js100%100%100%100%
   Dependency.js98.15%100%100%98.15%382, 428
   DependencyTemplate.js100%100%100%100%
   DependencyTemplates.js100%100%100%100%
   DotenvPlugin.js98.41%100%100%98.41%378, 391–392
   DynamicEntryPlugin.js100%100%100%100%
   EntryOptionPlugin.js100%100%100%100%
   EntryPlugin.js100%100%100%100%
   Entrypoint.js100%100%100%100%
   EnvironmentPlugin.js97.14%100%100%97.14%49
   ErrorHelpers.js100%100%100%100%
   EvalDevToolModulePlugin.js100%100%100%100%
   EvalSourceMapDevToolPlugin.js100%100%100%100%
   ExportsInfo.js100%100%100%100%
   ExportsInfoApiPlugin.js100%100%100%100%
   ExternalModule.js98.66%100%100%98.66%1057, 1060, 445–449, 597
   ExternalModuleFactoryPlugin.js100%100%100%100%
   ExternalsPlugin.js100%100%100%100%
   FileSystemInfo.js99.50%100%100%99.50%182, 2252–2253, 2256, 2267, 2278, 2289, 278, 3693, 3708, 3732
   FlagAllModulesAsUsedPlugin.js100%100%100%100%
   FlagDependencyExportsPlugin.js98.46%100%100%98.46%425, 434, 436, 440
   FlagDependencyUsagePlugin.js100%100%100%100%
   FlagEntryExportAsUsedPlugin.js100%100%100%100%
   Generator.js100%100%100%100%
   HotModuleReplacementPlugin.js100%100%100%100%
   HotUpdateChunk.js100%100%100%100%
   IgnorePlugin.js100%100%100%100%
   IgnoreWarningsPlugin.js100%100%100%100%
   InitFragment.js100%100%100%100%
   JavascriptMetaInfoPlugin.js100%100%100%100%
   LibraryTemplatePlugin.js100%100%100%100%
   LoaderOptionsPlugin.js100%100%100%100%
   LoaderTargetPlugin.js100%100%100%100%
   MainTemplate.js100%100%100%100%
   ManifestPlugin.js100%100%100%100%
   Module.js98.50%100%100%98.50%1285, 1290, 1350, 1364, 1426, 1435
   ModuleFactory.js100%100%100%100%
   ModuleFilenameHelpers.js98.85%100%100%98.85%106, 108
   ModuleGraph.js99.73%100%100%99.73%1005
   ModuleGraphConnection.js100%100%100%100%
   ModuleInfoHeaderPlugin.js100%100%100%100%
   ModuleNotFoundError.js100%100%100%100%
   ModuleProfile.js100%100%100%100%
   ModuleSourceTypeConstants.js100%100%100%100%
   ModuleTemplate.js100%100%100%100%
   ModuleTypeConstants.js100%100%100%100%
   MultiCompiler.js99.69%100%100%99.69%659
   MultiStats.js100%100%100%100%
   MultiWatching.js100%100%100%100%
   NoEmitOnErrorsPlugin.js100%100%100%100%
   NodeStuffPlugin.js100%100%100%100%
   NormalModule.js97.90%100%100%97.90%1240, 1243, 1260, 1277, 1524, 1558, 1574, 1661, 2017, 2316, 2321–2331, 419, 423, 577
   NormalModuleFactory.js99.47%100%100%99.47%1083, 1392, 486, 498
   NormalModuleReplacementPlugin.js100%100%100%100%
   NullFactory.js100%100%100%100%
   OptimizationStages.js100%100%100%100%
   OptionsApply.js100%100%100%100%
   Parser.js100%100%100%100%
   PlatformPlugin.js100%100%100%100%
   PrefetchPlugin.js100%100%100%100%
   ProgressPlugin.js98.85%100%100%98.85%519–520, 525, 527, 591
   ProvidePlugin.js100%100%100%100%
   RawModule.js100%100%100%100%
   RecordIdsPlugin.js100%100%100%100%
   RequestShortener.js100%100%100%100%
   ResolverFactory.js100%100%100%100%
   RuntimeGlobals.js100%100%100%100%
   RuntimeModule.js100%100%100%100%
   RuntimePlugin.js100%100%100%100%
   RuntimeTemplate.js100%100%100%100%
   SelfModuleFactory.js100%100%100%100%
   SingleEntryPlugin.js100%100%100%100%
   SourceMapDevToolModuleOptionsPlugin.js100%100%100%100%
   SourceMapDevToolPlugin.js98.62%100%100%98.62%220, 224, 226, 419, 430, 891
   Stats.js100%100%100%100%
   Template.js100%100%100%100%
   TemplatedPathPlugin.js99.17%100%100%99.17%176–177
   UseStrictPlugin.js100%100%100%100%
   WarnCaseSensitiveModulesPlugin.js100%100%100%100%
   WarnDeprecatedOptionPlugin.js100%100%100%100%
   WarnNoModeSetPlugin.js100%100%100%100%
   WatchIgnorePlugin.js100%100%100%100%
   Watching.js100%100%100%100%
   WebpackError.js100%100%100%100%
   WebpackIsIncludedPlugin.js100%100%100%100%
   WebpackOptionsApply.js100%100%100%100%
   WebpackOptionsDefaulter.js100%100%100%100%
   buildChunkGraph.js99.87%100%100%99.87%371
   cli.js98.62%100%100%98.62%10, 119, 545, 577, 627, 897
   index.js99.72%100%100%99.72%179
   validateSchema.js94.67%100%100%94.67%100, 87, 89, 98
   webpack.js96.33%100%100%96.33%10, 198, 220, 222
lib/asset
   AssetBytesGenerator.js100%100%100%100%
   AssetBytesParser.js100%100%100%100%
   AssetGenerator.js100%100%100%100%
   AssetModule.js100%100%100%100%
   AssetModulesPlugin.js97.32%100%100%97.32%281, 305, 308, 36, 360, 41
   AssetParser.js100%100%100%100%
   AssetSourceGenerator.js100%100%100%100%
   AssetSourceParser.js100%100%100%100%
   RawDataUrlModule.js100%100%100%100%
lib/async-modules
   AsyncModuleHelpers.js100%100%100%100%
   AwaitDependenciesInitFragment.js100%100%100%100%
   InferAsyncModulesPlugin.js100%100%100%100%
lib/cache
   AddBuildDependenciesPlugin.js100%100%100%100%
   AddManagedPathsPlugin.js100%100%100%100%
   IdleFileCachePlugin.js97.92%100%100%97.92%71, 83, 91
   MemoryCachePlugin.js95.83%100%100%95.83%33
   MemoryWithGcCachePlugin.js93.15%100%100%93.15%106, 113–114, 122, 89
   PackFileCacheStrategy.js96.40%100%100%96.40%1250, 1350, 1354, 1416, 628, 647, 657–659, 661, 677–678, 683, 686, 688, 693, 698, 722, 728, 762, 768, 774, 779, 790, 799, 804–805, 807, 824, 830–831, 833
   ResolverCachePlugin.js100%100%100%100%
   getLazyHashedEtag.js100%100%100%100%
   mergeEtags.js100%100%100%100%
lib/config
   browserslistTargetHandler.js100%100%100%100%
   defaults.js99.31%100%100%99.31%1439–1441, 1449, 274, 277, 282, 286
   normalization.js99.01%100%100%99.01%191–192, 258, 273
   target.js100%100%100%100%
lib/container
   ContainerEntryDependency.js100%100%100%100%
   ContainerEntryModule.js100%100%100%100%
   ContainerEntryModuleFactory.js100%100%100%100%

@alexander-akait alexander-akait merged commit 80f5ed8 into main Jun 17, 2026
65 of 66 checks passed
@alexander-akait alexander-akait deleted the feat/universal-worker-instantiation branch June 17, 2026 09:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant