eslint-ts-patch

Support loading eslint.config.mjs or eslint.config.ts as flat config file for ESLint.

Configure files will be searched in the following order, the first one found will be used:

• eslint.config.js
• eslint.config.mjs
• eslint.config.cjs
• eslint.config.ts
• eslint.config.mts
• eslint.config.cts

For .js, .cjs, and .mjs files, they will be loaded by Node's native import().

For .ts, .cts, and .mts files, they will be loaded using TypeScript loaders.

Context:

• Unfortunately ESLint team decided to not support the detection of .cjs and .mjs as flat config.
• Update: ESLint v8.57.0 added support for eslint.config.mjs and eslint.config.cjs.
• Native ESLint support for eslint.config.ts has been merged (not released yet): PR, Original RFC - This package will soon be redundant when it's landed.

Install

npm i -D eslint-ts-patch eslint@npm:eslint-ts-patch

It should make your eslint CLI work for those config files automatically. If it's still not, you can try switching the CLI to eslint-ts.

TypeScript Loaders

There are multiple solutions to load TypeScript files in Node.js at runtime, and each of them consists of different trade-offs. This patch supports the following loaders powered by importx:

• default: Auto-detect the loader based on the user's environment.
• tsx - Use Node's native ESM loader to load TypeScript files.
  • Pros: Use Node's native ESM loader, running in ESM. Should have the most correct behavior.
  • Cons: It requires Node.js v18.19.0+ or v20.8.0. Refer to the Compatibility section.
• jiti- Transpile TypeScript files and ESM to CJS and execute them at runtime.
  • Pros: Easy to use. No need to install additional dependencies.
  • Cons: Everything is in CJS mode. It does not support top-level-await. It may have inconsistent behavior during ESM/CJS interop.
• bundle-require - Use esbuild to bundle the eslint.config.ts file, and import the temporary bundle.
  • Pros: Not hacking into Node's internals. ESM and top-level-await are supported.
  • Cons: It writes a temporary file to disk.

Learn more about the loaders in the importx documentation.

To try out different loaders, you can set the ESLINT_TS_PATCH_LOADER environment variable to one of the following values:

ESLINT_TS_PATCH_LOADER=tsx npx eslint
ESLINT_TS_PATCH_LOADER=bundle-require npx eslint

Or you can use magic comments @eslint-ts-patch-loader in your eslint.config.ts file:

// @eslint-ts-patch-loader tsx

Compatibility

Tested with the following tools:

Package Managers

• npm ✅
• pnpm ✅
• yarn ✅

Integrations

• eslint CLI ✅
• VSCode ESLint extension ⚠️ (as it's executing your local node_modules/.bin/eslint)

As for VS Code v1.89 (April 2024) the bundled Node is v18.18.2, which is not compatible with tsx loader (requires v18.19.0+) - Which should be fixed with next month's VS Code release. In order for VS Code ESLint works now, you need to update your settings.json with the following config to use your global Node.js:

{
  "eslint.runtime": "node"
}

Versioning

This package proxies all ESLint exports, it should be compatible by aliasing the eslint package. The version of this package is the same as the latest supported ESLint version in addition to a patch number suffix indicating the patches of this package (e.g. 8.55.0-1). It's using ^ relaxed dependency of eslint, so it should work with any newer versions of ESLint.

How it works

As the support of eslint.config.js seems to be quite hard-coded in ESLint, this package proxies all exports of ESLint and installs this register beforehand. The register will swap some internal code of ESLint at runtime to make it work.

Disclaimer

It's only recommended to install this as top-level development dependency (user-aware). For plugin and library authors, it's ok to document the usage of this package for better DX. But we suggest avoiding having this as the dependency of your library or plugin, otherwise, take your own risk.

Troubleshooting

Is the Patch Working

This patch is designed to be as transparent as possible. If you want to verify if it's working, you can add DEBUG="eslint-ts-patch" environment variable to your command to see the debug logs.

➜ DEBUG="eslint-ts-patch" npx eslint -v

  eslint-ts-patch initialized +0ms
  eslint-ts-patch patched lib/eslint/flat-eslint.js +59ms

v8.55.0

Sponsors

License

MIT License © 2023-PRESENT Anthony Fu