Improve `@babel/core` types #17404

liuxingbaoyu · 2025-06-27T18:21:03Z

Q	A
Fixed Issues?	`Fixes #1, Fixes #2`
Patch: Bug Fix?
Major: Breaking Change?
Minor: New Feature?
Tests Added + Pass?	Yes
Documentation PR Link
Any Dependency Changes?
License	MIT

The main change is to distinguish InputOptions from ValidatedOptions, because they have two different fields.

To be honest, I don't want to expose some internal types such as Plugin or even ValidatedOptions details.
But I didn't think of a good way.

liuxingbaoyu · 2025-06-27T18:22:54Z

packages/babel-core/src/config/validation/options.ts

+  | ((api: PluginAPI, options?: object, dirname?: string) => PluginObject);
 export type PluginItem =
  | ConfigItem<PluginAPI>
-  | Plugin


This is a change, Plugin is our internal class and should not be accepted.

babel-bot · 2025-06-27T18:23:16Z

Build successful! You can test your changes in the REPL here: https://babeljs.io/repl/build/60052

liuxingbaoyu · 2025-06-27T18:24:27Z

packages/babel-core/src/config/full.ts


      for (let i = 0; i < rawPresets.length; i++) {
        const descriptor = rawPresets[i];
+        // @ts-expect-error TODO: disallow false


What do you think?
Currently Babel accepts ["plugin", false] to disable a plugin, is there any reason for this?

liuxingbaoyu · 2025-06-27T18:26:51Z

To be honest, I don't want to expose some internal types such as Plugin or even ValidatedOptions details.
But I didn't think of a good way.

Currently some private properties are also exposed, I will open a new PR.

packages/babel-core/src/index.ts

packages/babel-preset-typescript/src/index.ts

packages/babel-preset-react/src/index.ts

pkg-pr-new · 2025-07-28T20:41:08Z

Open in StackBlitz

commit: 030d0c1

liuxingbaoyu · 2025-07-31T07:34:37Z

packages/babel-core/src/transformation/normalize-opts.ts

+  const options: BaseOptions = {
    ...opts,

    parserOpts: {
      sourceType:
        path.extname(filenameRelative) === ".mjs" ? "module" : sourceType,

+      // @ts-expect-error FIXME: should be sourceFilename
      sourceFileName: filename,


This is a bug, but requires a more complex fix, which I'll include in a separate PR.

packages/babel-core/src/config/index.ts

packages/babel-preset-env/src/index.ts

liuxingbaoyu · 2025-08-22T20:33:24Z

packages/babel-core/src/config/config-descriptors.ts

  filepath: string;
  dirname: string;
-  options: ValidatedOptions;
+  options: InputOptions;


This isn't ideal, but I haven't figured out a better solution yet.

JLHwung

I agree that we should probably stop exporting ValidatedOptions, but we still have to export InputOptions and NormalizedOptions, since the latter can be accessed from the return result of the loadPartialConfig API via the .options property.

JLHwung · 2025-08-27T16:03:07Z

packages/babel-core/src/config/validation/options.ts

+  plugins?: Plugin[];
+};
+
 export type NormalizedOptions = {


Could you add JSDoc description comments on InputOptions, ValidatedOptions and NormalizedOptions?
Based on the shape it seems to me that ValidatedOptions is the option after the plugins / presets are resolved, and NormalizedOptions is the option after targets are resolved. But the their namings currently do not really indicate their lifecycles.

And among them only InputOptions are exported to users right?

I did some refactoring, and it looks much better now.

Renamed ValidatedOptions to ResolvedOptions

Better defined NormalizedOptions so it can now be assigned to InputOptions.

I hesitated about exporting ResolvedOptions; obviously, we don't want users to read or write it, but as a public function return value, exporting it would make caching easier for users.

NormalizedOptions has been exported.

Better defined NormalizedOptions so it can now be assigned to InputOptions.

I don't think it is safe to assign NormalizedOptions to an InputOptions, because:

InputOptions is the options for the API users, we will then provide defaults, enforces validations and resolve plugins/ presets so that it became a ResolvedOptions. Then we resolve targets and it became NormalizedOptions. At this point, the targets are readonly, plugins are resolved, it should not be cast to an InputOptions -- since we are not going to resolve targets / plugins again.

If there are typing errors for doing so, maybe those methods actually expects NormalizedOptions rather than InputOptions and we should then update those methods.

From what I understand, InputOptions will first become NormalizedOptions and then become ResolvedOptions?
We have an existing usage in eslint-parser of passing loadPartialConfigSync().options into parseSync which seems to be acceptable.

Okay. If that's the case, that means ResolvedOptions must be made a subset type of InputOptions, so we should export the internal resolved plugin type, since it is indeed accepted by our API.

Could you explain more, thanks!

Sorry, I don't understand what you mean. The API accepts NormalizedOptions but not ResolvedOptions.

Sorry for the late reply. Let me try to elaborate a bit.

The parseSync accepts InputOptions.

babel/packages/babel-core/src/parse.ts

Line 26 in 900e5d1

opts: InputOptions | undefined | null,

Now if parseSync also supports the return result of loadPartialConfigSync().options, then the NormalizedOptions, returned from loadPartialConfigSync().options,

babel/packages/babel-core/src/config/partial.ts

Line 204 in 900e5d1

options: NormalizedOptions;

should be automatically also a valid InputOptions. This implies that ConfigItem<PluginAPI>[] should be accepted in InputOptions, because of the usage in eslint-parser. And Plugin should be broaden to include ConfigItem<PluginAPI>.

Thanks for the detailed explanation.
It looks like PluginItem already contains ConfigItem<PluginAPI>?

And Plugin should be broaden to include ConfigItem.

Sorry for any confusion here. To clarify, Plugin is not an typo of PluginItem. I refer to the Plugin type defined here:

babel/packages/babel-core/src/config/plugin.ts

Line 5 in 61ad855

export default class Plugin {

nested within the ResolvedConfig in packages/babel-core/src/config/full.ts.

Since ResolvedOptions is allowed as an InputOption because of the usage in eslint-parser, we should make typing adjustments to InputOptions such that any ResolvedOptions will also satisfy InputOptions, but not the opposite. Or we provide overload signatures to the API for the ResolvedOptions support.

The goal here is that end users should not cast typings if they only use Babel API, as long as the API accepts such inputs.

I checked and it seems that eslint-parser does not use ResolvedOptions, although there is a function called validateResolvedConfig, it actually returns still InputOptions | NormalizedOptions.

JLHwung · 2025-08-27T16:06:32Z

packages/babel-core/src/config/index.ts

 export type {
  CallerMetadata,
  NormalizedOptions,
  ValidatedOptions as PresetObject,


Is this type export still used now that we have created PresetObject type in the root index.ts?

JLHwung · 2025-08-27T16:11:27Z

packages/babel-core/src/config/partial.ts

  });

-  const options: NormalizedOptions = {
+  const options: InputOptions = {


We only resolve the targets here, isn't the options here the NormalizedOptions? That is, the targets should be considered read-only because it won't be resolved again if they are somehow modified by plugins.

nicolo-ribaudo · 2025-09-12T10:34:22Z

packages/babel-core/src/index.ts

+  PluginItem,
+} from "./config/validation/options.ts";
 export { loadOptionsSync };
+export type { PluginItem };


Thanks for this, currently for Jest I had to use type PluginItem = NonNullable<BabelOptions['plugins']>[number]; instead 😅

JLHwung

Aside: I also noticed that there is another normalizeOptions routine:

babel/packages/babel-core/src/config/config-chain.ts

Line 739 in 61ad855

function normalizeOptions(opts: ValidatedOptions): ValidatedOptions {

I think this routine can be renamed to createConfigChainOptions and we should create a new ConfigChainOptions type for it, it is also a subset of InputOptions but with quite a few properties removed. This should catch errors if we try to access those properties from the config chain options.

JLHwung · 2025-09-22T15:36:45Z

packages/babel-core/src/transformation/normalize-opts.ts

 export default function normalizeOptions(
  config: ResolvedConfig,
-): NormalizedOptions {
+): ResolvedOptions {


The type NormalizedOptions is named after this routine, it would be very confusing if this routine returns ResolvedOptions. Maybe we can rename it as buildResolvedConfigOptions or something.

JLHwung · 2025-09-22T16:03:12Z

packages/babel-core/src/config/validation/options.ts

+  plugins?: Plugin[];
+};
+
 export type NormalizedOptions = {


Sorry, I don't understand what you mean. The API accepts NormalizedOptions but not ResolvedOptions.

Sorry for the late reply. Let me try to elaborate a bit.

The parseSync accepts InputOptions.

babel/packages/babel-core/src/parse.ts

Line 26 in 900e5d1

opts: InputOptions | undefined | null,

Now if parseSync also supports the return result of loadPartialConfigSync().options, then the NormalizedOptions, returned from loadPartialConfigSync().options,

babel/packages/babel-core/src/config/partial.ts

Line 204 in 900e5d1

options: NormalizedOptions;

should be automatically also a valid InputOptions. This implies that ConfigItem<PluginAPI>[] should be accepted in InputOptions, because of the usage in eslint-parser. And Plugin should be broaden to include ConfigItem<PluginAPI>.

Co-authored-by: Huáng Jùnliàng <[email protected]>

liuxingbaoyu commented Jun 27, 2025

View reviewed changes

JLHwung reviewed Jul 28, 2025

View reviewed changes

packages/babel-core/src/index.ts Outdated Show resolved Hide resolved

JLHwung reviewed Jul 28, 2025

View reviewed changes

packages/babel-preset-typescript/src/index.ts Outdated Show resolved Hide resolved

JLHwung reviewed Jul 28, 2025

View reviewed changes

packages/babel-preset-react/src/index.ts Outdated Show resolved Hide resolved

liuxingbaoyu force-pushed the improve-core-types branch from 827283d to 94299e4 Compare July 31, 2025 07:26

liuxingbaoyu commented Jul 31, 2025

View reviewed changes

packages/babel-core/src/config/index.ts Outdated Show resolved Hide resolved

liuxingbaoyu mentioned this pull request Jul 31, 2025

Removed incorrect options #17458

Open

liuxingbaoyu force-pushed the improve-core-types branch from 0765993 to e139554 Compare August 22, 2025 19:39

JLHwung reviewed Aug 22, 2025

View reviewed changes

packages/babel-preset-env/src/index.ts Outdated Show resolved Hide resolved

liuxingbaoyu commented Aug 22, 2025

View reviewed changes

JLHwung reviewed Aug 27, 2025

View reviewed changes

liuxingbaoyu force-pushed the improve-core-types branch from f626409 to 900e5d1 Compare August 28, 2025 22:47

liuxingbaoyu added pkg: core PR: Polish (next major) 💅 A type of pull request used for our changelog categories for next major release labels Sep 4, 2025

liuxingbaoyu requested a review from JLHwung September 9, 2025 17:33

nicolo-ribaudo approved these changes Sep 12, 2025

View reviewed changes

JLHwung reviewed Sep 22, 2025

View reviewed changes

liuxingbaoyu force-pushed the improve-core-types branch from ea0f6bb to 8f32ea5 Compare September 30, 2025 15:00

liuxingbaoyu and others added 7 commits October 3, 2025 17:05

improve types

6db9701

Apply suggestions from code review

2e1ae5a

Co-authored-by: Huáng Jùnliàng <[email protected]>

review

fd81c1c

improve

96a6fd6

improve

084808d

fix rebase

7317505

FIXME

921f020

Uh oh!

Improve @babel/core types #17404

Improve @babel/core types #17404

Uh oh!

Conversation

liuxingbaoyu commented Jun 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

babel-bot commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liuxingbaoyu commented Jun 27, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JLHwung left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JLHwung Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JLHwung left a comment

Choose a reason for hiding this comment

Uh oh!

JLHwung Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Improve `@babel/core` types #17404

Improve `@babel/core` types #17404

babel-bot commented Jun 27, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 28, 2025 •

edited

Loading

JLHwung Sep 23, 2025 •

edited

Loading

JLHwung Sep 22, 2025 •

edited

Loading