Move `webpack/webpack` to TypeScript

[avivkeller]

I'd like us to seriously consider migrating webpack core from JavaScript-with-JSDoc to TypeScript, compiling down to JavaScript on release so that nothing changes for consumers in non-TS environments.

After a few weeks investigating how we generate our type definitions, my conclusion is that our current setup has reached the point where it costs us more than it gives us. The combination of TypeScript + CommonJS + JSDoc does not interact well, and the workarounds we've built to make it interact are a maintenance burden.

Webpack core ships a types.d.ts file that consumers depend on. That file is generated from 18,000+ JSDoc comments annotations across the source tree. Plain tsc --declaration --allowJs --emitDeclarationOnly is not sufficient to produce the types.d.ts we ship. We rely on a custom generator at webpack/tooling/generate-types that wraps the TypeScript compiler API and post-processes its output.

The custom tooling exists because the "official" path (letting tsc emit declarations from JSDoc) falls short in several practical ways for a codebase of webpack's size and shape:

• Cross-file inference through CommonJS require boundaries is fragile.
• Internal symbols leak into public declarations unless explicitly pruned. (For instance, the wall of @typedef-s in every file)
• Declaration merging and module-augmentation patterns common in plugin APIs are hard to express purely in JSDoc.

The result is a pipeline where we run tsc against all of our .js files for type-checking (treating them as TypeScript via checkJs), and then run a separate, custom generator to produce the shipped declarations. We pay the cost of being a TypeScript project without getting the primary benefit of being one.

Stated plainly: JSDoc was not designed to be a TypeScript source format. TypeScript's JSDoc support was added pragmatically, so projects could opt into type-checking without rewriting source files. It is not a great primary authoring format for an 18,000-annotation codebase whose public type surface is itself a deliverable. We are paying TypeScript's costs (compiler in the loop, type-check step in CI, custom generator) while authoring in a format that was never meant to scale to this size.

So, I propose we, slowly of course, move the entire webpack core repository to TypeScript source. Compile to JavaScript at build/release time so that downstream consumers, including non-TS environments and Node-as-runtime use cases, see no functional change. The shipped types.d.ts is generated by tsc directly from .ts sources, the way TypeScript was designed to work.

Essentially,

• lib/**/*.js → lib/**/*.ts.
• The custom generate-types pipeline (and related pipelines) is retired in favor of tsc --declaration.
• The published npm package still contains compiled .js plus .d.ts.
• CI runs tsc once, as the authoritative type-checker and declaration emitter, instead of running tsc and the custom generator in series.

Note

GSoC 2026 is starting soon. GSoC candidates will be relying on the types.d.ts file for the new documentation. While this should not interact with their project, it may be best to discuss implementation after GSoC concludes. My suggested target for this would be webpack 7.

[alexander-akait]

I don't think we need to, we already have typescript using jsdocs and it works great, why:

• Extra step to build
• TypeScript + CommonJS + JSDoc - we will move from commonjs in future
• Typescript generates extra code in some cases and unoptimized code (we thought about it before and it was a big blocker)
• JSDoc was not designed to be a TypeScript source format, disagree - they officially support it and want to continue support (by the way if you look at some project why performance cost, most of them migrate from typescript to js + jsdocs, it is faster, it is more control)
• I don't think we have time to do it, we already have strict types around 99% + git history will be bad

I am not again typescript, I like it, but jsdocs fits good for us

[avivkeller]

Extra step to build

I don't think this "extra step" is a blocker, we already run tsc on our entire codebase, so this would be a modification of that command, not an addition of a new one. In fact, it would remove commands such as type generation, so it would probably remove a build step.

Typescript generates extra code in some cases and unoptimized code (we thought about it before and it was a big blocker)

TypeScript generates extra code when you use it for type transformations (e.g. enum). In our case, we would use it exclusively for stripping the types away from mostly JavaScript-equal code, so this shouldn't be a problem.

JSDoc was not designed to be a TypeScript source format, disagree - they officially support it and want to continue support (by the way if you look at some project why performance cost, most of them migrate from typescript to js + jsdocs, it is faster, it is more control)

TypeScript officially supports JSDoc and continues improving that support, however, JSDoc was originally created for JavaScript documentation, not as the primary TypeScript source language. TypeScript’s own design centers around native type syntax in .ts files, and JSDoc support is best understood (from my own understanding) as interoperability and migration support rather than proof that JSDoc is the intended "replacement" for TypeScript.

[alexander-akait]

I don't think this "extra step" is a blocker, we already run tsc on our entire codebase, so this would be a modification of that command, not an addition of a new one. In fact, it would remove commands such as type generation, so it would probably remove a build step.

No, we use it as an additional check, if you want to debug something directly you can do it without any extra actions, just put debugger, console.log and other additional things

TypeScript generates extra code when you use it for type transformations (e.g. enum). In our case, we would use it exclusively for stripping the types away from mostly JavaScript-equal code, so this shouldn't be a problem.

Yes, we can do it, but we have a lot of hacks in JS (prototype change, using null/undefined for reduce memory consummation, some hacks to add depredations and more) to be faster and reduce memory consuming, but typescript directly (to generate types) doesn't allow to do it or bring a lot of @ts-expected-error

TypeScript officially supports JSDoc and continues improving that support, however, JSDoc was originally created for JavaScript documentation, not as the primary TypeScript source language.

I disagree, it is a good feature and officially support, I don't see - We don't recommend to use it, or some problems with it, rewriting huge сщву just to make it look a little different is a massive waste of time and can potentially break things

We have roadmap for 2026 and should work with these things