feat: Add support for TypeScript config files

[aryaemami59]

Summary

Add support for TypeScript config files (eslint.config.ts, eslint.config.mts, eslint.config.cts).

Related Issues

This PR is related to this RFC.

[bradzacher]

Worth linking the prior art in this area: #50

[kecrily]

I think it makes sense and is low cost to support this in a runtime that supports ts natively. Like deno and bun, we can just import them.

[aryaemami59]

@bradzacher Yes thank you!!!

[bmish]

How does the feature interact with the CLI option --config for specifying a config file?

[aryaemami59]

I have tested it, so far it seems to work pretty well actually, especially with v9. I'm probably going to write a bunch of tests as well to see if there are any edge cases but so far so good.

[bmish]

It would be good to explain what the behavior is when specifying TS or non-TS config files of varying file extensions through that option.

[aryaemami59]

It doesn't behave any differently, same as before. You can do eslint . --config=eslint.config.ts or eslint . -c eslint.config.ts and they just work. Same as with a eslint.config.js file.

[nzakas]

Can you add that into the RFC?

[aryaemami59]

I added it to the open questions, is that fine?

[ljharb]

Which version of TypeScript can the config file be written in? With what tsconfig settings?

Does this mean eslint would need to depend on typescript, causing it to be installed for non-TS users? if not, then would eslint be able to consume typescript in pnpm and yarn pnp in order to transpile the eslint config?

[bradzacher]

if not, then would eslint be able to consume typescript in pnpm and yarn pnp in order to transpile the eslint config?

It's possible to declare an implicit, optional peer dependency in a way that both yarn and pnpm will respect.

{
  "peerDependenciesMeta": {
    "typescript": {
      "optional": true
    }
  },
}

You don't even need to declare an explicit peer dependency with this config as it implicitly declares a dep on typescript: "*".

For context this is how the @typescript-eslint packages depend on TypeScript.

[aryaemami59]

@ljharb

Which version of TypeScript can the config file be written in?

We are going to be using jiti to transpile the TypeScript config files. It has been used by frameworks such as Nuxt, Tailwind CSS and Docusaurus for this exact purpose. As far as I'm aware of, the only limitation it has, is that it doesn't yet support top-level await. The latest TypeScript syntax that I can think of that would also be relevant to our situation is the satisfies operator which I have made sure jiti has no problem with as I used it recently to do the exact same thing with size-limit.

With what tsconfig settings?

As far as I know, jiti does not care about tsconfig settings. It doesn't work like ts-node. I believe it uses babel internally to do the transpilling and it provides an interopDefault option to allow for using either export default and module.exports which in this situation would be very helpful as users will not have to worry about ESM/CJS compatibility issues.

Does this mean eslint would need to depend on typescript, causing it to be installed for non-TS users? if not, then would eslint be able to consume typescript in pnpm and yarn pnp in order to transpile the eslint config?

I think jiti will have to become either a dependency or an optional dependency. And we could make TypeScript an optional peer dependency as to not force the non-TS users to install it.

[nzakas]

Thanks for putting this together. I left some answers to the open questions. Also, we like to have a detailed design right in the RFC explaining where you'd make changes and how Jiti would be used.

[nzakas]

Can you add that into the RFC?

[fasttime]

Thanks for this RFC @aryaemami59! Could it be that Jiti doesn't transpile top-level await expressions properly? For example, the following config is throwing an error for me:

// eslint.config.mts
const { default: globals } = await import('globals');

export default {
    languageOptions: {
        globals: globals.node
    },
    rules: {
        'no-undef': 'error'
    }
};

SyntaxError: await is only valid in async functions and the top level bodies of modules

Would it be possible to add a note to the RFC to state this limitation - or if I'm overlooking something, explain how to make top-level await work?

It would be good to have this noted either way to make sure that we don't forget to add unit tests during the implementation.

[aryaemami59]

Thanks for this RFC @aryaemami59! Could it be that Jiti doesn't transpile top-level await expressions properly?
Would it be possible to add a note to the RFC to state this limitation - or if I'm overlooking something, explain how to make top-level await work?

@fasttime Yeah I mentioned it in this comment but I can go ahead and include it in the RFC as well. To my knowledge top level awaits are pretty much the only limitation jiti has. The library author did hint at a jiti.import method but it doesn't seem to be ready yet.

[fasttime]

@fasttime Yeah I mentioned it in this comment but I can go ahead and include it in the RFC as well. To my knowledge top level awaits are pretty much the only limitation jiti has. The library author did hint at a jiti.import method but it doesn't seem to be ready yet.

Yes, the lack of support for top-level await should be included in the RFC since it is an important limitation. If the RFC is accepted, we will also need to include it as a note in the documentation, along with other inconsistencies we may find while adding unit tests.

[aladdin-add]

there is a community project: https://github.com/antfu/eslint-ts-patch to support it. would like to hear the author :) / @antfu

[antfu]

It uses jiti to support ts file. Which already mentioned #117 (comment) that it doesn't currently support top-level await.

I would personally recommend using https://github.com/egoist/bundle-require instead which is more robust and will respect tsconfig.json. The downside is that it would introduce esbuild into the dependency. If the install size is a concern, I guess we could have an optional package like @eslint/config-loader-ts that only requires when users use ts version of config.

[MrHBS]

Looks like @eslint/config-inspector uses bundle-require as well.

[antfu]

Yes, the inspector uses that because we need to know the dependencies of the config to do automatic reloads. Supporting TS was a free side-effect.

Even if ESLint doesn't need information on dependencies, I think it's still a good way to support TS. Vite uses the same approach to load vite.config.ts.

[silverwind]

Does bundle-require write a temp file to disk like vite does?

These temp files are a major source of problems with vite, see vitejs/vite#9470.

[privatenumber]

Personally, I see TLA as a language spec requirement, and I don't think whether to support it should be up to whether we can imagine use-cases.

But if we want evaluate usage, here are examples of TLA in configs (Vite, Rollup, Next, Jest, esbuild, etc):
https://github.com/search?q=path%3A%2F%5C.config%5C.%28js%7Cts%29%24%2F+%2F%5Eawait+%2F&type=code

---

tsx is mentioned as a non-viable alternative because it uses custom loaders. Does that also hold when tsImport() is used?

tsImport() is isolated and won't add TypeScript support to the rest of the environment.

But just to be clear, I'm only sharing it as an option. Personally, I would like to have popular compilers supported as optional peer dependencies to accommodate different preferences and environments.

[fasttime]

Personally, I see TLA as a language spec requirement, and I don't think whether to support it should be up to whether we can imagine use-cases.

But if we want evaluate usage, here are examples of TLA in configs (Vite, Rollup, Next, Jest, esbuild, etc): https://github.com/search?q=path%3A%2F%5C.config%5C.%28js%7Cts%29%24%2F+%2F%5Eawait+%2F&type=code

Interesting. There are also ESLint configs that use TLA: https://github.com/search?q=path%3A%2Feslint%5C.config%5C.m%3Fjs%24%2F+%2F%5Econst+.%2B+%3D+await+%2F&type=code.

[nzakas]

There is already a workaround for TLA available:

export default (async () => {
     await whatever();

}());

We await the export of the config file. We ran into this when discussing CommonJS support.

[fasttime]

Jiti won't recognize TLA not only in the config file itself, but also in imported modules, because they are all treated as CommonJS. I did a quick test using a patched version of ESLint with the changes from #18134 and with this config:

// eslint.config.ts
export { default } from './recommended.mjs';

// recommended.mjs
import { readFile } from 'node:fs/promises';

const json = await readFile('package.json', 'utf-8');
const { name } = JSON.parse(json);

export default [{ name, rules: { 'no-undef': 'error' } }];

When running eslint, I got an error as expected:

Oops! Something went wrong! :(

ESLint: 9.2.0

ReferenceError: await is not defined
    at ../project/recommended.mjs:4:14
    at evalModule (../project/node_modules/eslint/node_modules/jiti/dist/jiti.js:1:256443)
    at jiti (../project/node_modules/eslint/node_modules/jiti/dist/jiti.js:1:254371)
    at ../project/eslint.config.ts:2:43
    at evalModule (../project/node_modules/eslint/node_modules/jiti/dist/jiti.js:1:256443)
    at jiti (../project/node_modules/eslint/node_modules/jiti/dist/jiti.js:1:254371)
    at loadFlatConfigFile (../project/node_modules/eslint/lib/eslint/eslint.js:335:24)
    at async calculateConfigArray (../project/node_modules/eslint/lib/eslint/eslint.js:421:28)
    at async ESLint.lintFiles (../project/node_modules/eslint/lib/eslint/eslint.js:840:25)
    at async Object.execute (../project/node_modules/eslint/lib/cli.js:500:23)
    at async main (../project/node_modules/eslint/bin/eslint.js:153:22)

The workaround of using a dynamic import didn't help either, and resulted in the same error:

// eslint.config.ts
export default (async () =>
    (await import('./recommended.mjs')).default
)();

This means that if we decide to use Jiti, plugin developers should be advised to avoid TLA in their shared configs (including rules and transitive dependencies), or else those configs will not work for users who have a eslint.config.ts in their project.

[antfu]

I added support for all the ts loaders we mentioned in eslint-ts-patch and listed their trade-offs, where you can give them a try today.

[nzakas]

I think the jiti approach makes sense to me. It's fairly clean and even though it doesn't support top-level await, I think we can live with that.

[aladdin-add]

I'm conflicted about this requirement. While it may burden non-TypeScript users with an unnecessary dependency, TypeScript users are a significant part of the ESLint community. I'll defer to the team's judgment on this one.

[aladdin-add]

When using the ts configs, does it check the ts type, or is it just erasure typings?

[aladdin-add]

A feasible alternative is leaving it to the community, e.g. eslint-ts-patch. ts users just need to install it, and it just works.

[privatenumber]

I agree. As a user, I wouldn't want a TS compiler installed in non-TS projects, and I wouldn't want a second TS compiler installed if I already have one installed.

As a reference in postcss-load-config, tsx and jiti are optional peer dependencies so it's up to the user to provide:
https://github.com/postcss/postcss-load-config/blob/62d325c7c51fa536c433b2a2517e59d8f1ed101d/src/req.js#L18-L57

[nzakas]

@privatenumber I think that's good feedback. We could definitely specify TS-related stuff as an optional dependency and ask folks to manually install.

[silverwind]

Seems like a good call to require opt-in to these dependencies. Some runtimes like bun and deno support typescript out of the box so won't need this compiler. I think it's also likely that Node.js will gain native typescript support eventually, see nodejs/node#43816.

[nzakas]

Some runtimes like bun and deno support typescript out of the box so won't need this compiler.

That's true. In those runtimes the .ts file would just be loaded without any other dependencies.

[kecrily]

This is consistent with what I mentioned in #117 (comment). We can check the runtime and import it directly, otherwise keep looking for the ts loader