eslint · nzakas · Aug 8, 2024 · Feb 20, 2024 · Feb 20, 2024 · Feb 23, 2024
@@ -21,6 +21,9 @@ The ESLint configuration file may be named any of the following:
 * `eslint.config.js`
 * `eslint.config.mjs`
 * `eslint.config.cjs`
+* `eslint.config.ts` (requires [additional setup](#typescript-configuration-files))
+* `eslint.config.mts` (requires [additional setup](#typescript-configuration-files))
+* `eslint.config.cts` (requires [additional setup](#typescript-configuration-files))
 
 It should be placed in the root directory of your project and export an array of [configuration objects](#configuration-objects). Here's an example:
 
@@ -495,3 +498,84 @@ npx eslint --config some-other-file.js **/*.js
 ```
 
 In this case, ESLint does not search for `eslint.config.js` and instead uses `some-other-file.js`.
+
+## TypeScript Configuration Files
+
+::: warning
+This feature is currently experimental and may change in future versions.
+:::
+
+You need to enable this feature through the `unstable_ts_config` feature flag:
+
+```bash
+npx eslint --flag unstable_ts_config
+```
+
+For Deno and Bun, TypeScript configuration files are natively supported; for Node.js, you must install the optional dev dependency [`jiti`](https://github.com/unjs/jiti) in your project (this dependency is not automatically installed by ESLint):
+
+```bash
+npm install -D jiti
+# or
+yarn add --dev jiti
+# or
+pnpm add -D jiti
+```
+
+You can then create a configuration file with a `.ts`, `.mts`, or `.cts` extension, and export an array of [configuration objects](#configuration-objects). Here's an example in ESM format:
+
+```ts
+import js from "@eslint/js";
+import type { Linter } from "eslint";
+
+export default [
+  js.configs.recommended,
+  {
+    rules: {
+      "no-console": [0],
+    },
+  },
+] satisfies Linter.FlatConfig[];
+```
+
+Here's an example in CommonJS format:
+
+```ts
+import type { Linter } from "eslint";
+const eslint = require("@eslint/js");
+
+const config: Linter.FlatConfig[] = [
+  eslint.configs.recommended,
+  {
+    rules: {
+      "no-console": [0],
+    },
+  },
+];
+
+module.exports = config;
+```
+
+::: important
+ESLint does not perform type checking on your configuration file and does not apply any settings from `tsconfig.json`.
+:::
+
+::: warning
+As of now, [`jiti`](https://github.com/unjs/jiti) does not support [Top-level `await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await)
+:::
+
+### Configuration File Precedence
+
+If you have multiple ESLint configuration files, ESLint prioritizes JavaScript files over TypeScript files. The order of precedence is as follows:
+
+1. `eslint.config.js`
+2. `eslint.config.mjs`
+3. `eslint.config.cjs`
+4. `eslint.config.ts`
+5. `eslint.config.mts`
+6. `eslint.config.cts`
+
+To override this behavior, use the `--config` or `-c` command line option to specify a different configuration file:
+
+```bash
+npx eslint --flag unstable_ts_config --config eslint.config.ts
+```
@@ -28,7 +28,10 @@
                 "rollup-plugin-node-polyfills",
 
                 // FIXME: not sure why is eslint-config-eslint reported as unused
-                "eslint-config-eslint"
+                "eslint-config-eslint",
+
+                // Optional peer dependency used for loading TypeScript configuration files
+                "jiti"
             ]
         },
         "docs": {

@@ -340,16 +340,17 @@ const cli = {
     /**
      * Calculates the command string for the --inspect-config operation.
      * @param {string} configFile The path to the config file to inspect.
+     * @param {boolean} hasUnstableTSConfigFlag `true` if the `unstable_ts_config` flag is enabled, `false` if it's not.
      * @returns {Promise<string>} The command string to execute.
      */
-    async calculateInspectConfigFlags(configFile) {
+    async calculateInspectConfigFlags(configFile, hasUnstableTSConfigFlag) {
 
         // find the config file
         const {
             configFilePath,
             basePath,
             error
-        } = await locateConfigFileToUse({ cwd: process.cwd(), configFile });
+        } = await locateConfigFileToUse({ cwd: process.cwd(), configFile }, hasUnstableTSConfigFlag);
 
         if (error) {
             throw error;
@@ -454,7 +455,7 @@ const cli = {
             try {
                 const flatOptions = await translateOptions(options, "flat");
                 const spawn = require("cross-spawn");
-                const flags = await cli.calculateInspectConfigFlags(flatOptions.overrideConfigFile);
+                const flags = await cli.calculateInspectConfigFlags(flatOptions.overrideConfigFile, flatOptions.flags ? flatOptions.flags.includes("unstable_ts_config") : false);
 
                 spawn.sync("npx", ["@eslint/config-inspector@latest", ...flags], { encoding: "utf8", stdio: "inherit" });
             } catch (error) {

@@ -63,6 +63,8 @@ const { Retrier } = require("@humanwhocodes/retry");
 /** @typedef {import("../shared/types").RuleConf} RuleConf */
 /** @typedef {import("../shared/types").Rule} Rule */
 /** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
+/** @typedef {import('../cli-engine/cli-engine').CLIEngine} CLIEngine */
+/** @typedef {import('./legacy-eslint').CLIEngineLintReport} CLIEngineLintReport */
 
 /**
  * The options with which to configure the ESLint instance.
@@ -86,7 +88,7 @@ const { Retrier } = require("@humanwhocodes/retry");
  *      when a string.
  * @property {Record<string,Plugin>} [plugins] An array of plugin implementations.
  * @property {boolean} [stats] True enables added statistics on lint results.
- * @property {boolean} warnIgnored Show warnings when the file list includes ignored files
+ * @property {boolean} [warnIgnored] Show warnings when the file list includes ignored files
  * @property {boolean} [passOnNoPatterns=false] When set to true, missing patterns cause
  *      the linting operation to short circuit and not report any failures.
  */
@@ -100,8 +102,18 @@ const FLAT_CONFIG_FILENAMES = [
     "eslint.config.mjs",
     "eslint.config.cjs"
 ];
+const FLAT_CONFIG_FILENAMES_WITH_TS = [
+    ...FLAT_CONFIG_FILENAMES,
+    "eslint.config.ts",
+    "eslint.config.mts",
+    "eslint.config.cts"
+];
 const debug = require("debug")("eslint:eslint");
 const privateMembers = new WeakMap();
+
+/**
+ * @type {Map<string, string>}
+ */
 const importedConfigFileModificationTime = new Map();
 const removedFormatters = new Set([
     "checkstyle",
@@ -262,28 +274,59 @@ function compareResultsByFilePath(a, b) {
  * Searches from the current working directory up until finding the
  * given flat config filename.
  * @param {string} cwd The current working directory to search from.
+ * @param {boolean} hasUnstableTSConfigFlag `true` if the `unstable_ts_config` flag is enabled, `false` if it's not.
  * @returns {Promise<string|undefined>} The filename if found or `undefined` if not.
  */
-function findFlatConfigFile(cwd) {
+function findFlatConfigFile(cwd, hasUnstableTSConfigFlag) {
+    const filenames = hasUnstableTSConfigFlag ? FLAT_CONFIG_FILENAMES_WITH_TS : FLAT_CONFIG_FILENAMES;
+
     return findUp(
-        FLAT_CONFIG_FILENAMES,
+        filenames,
         { cwd }
     );
 }
 
+/**
+ * Check if the file is a TypeScript file.
+ * @param {string} filePath The file path to check.
+ * @returns {boolean} `true` if the file is a TypeScript file, `false` if it's not.
+ */
+function isFileTS(filePath) {
+    const fileExtension = path.extname(filePath);
+
+    return /^\.[mc]?ts$/u.test(fileExtension);
+}
+
+/**
+ * Check if ESLint is running in Bun.
+ * @returns {boolean} `true` if the ESLint is running Bun, `false` if it's not.
+ */
+function isRunningInBun() {
+    return !!globalThis.Bun;
+}
+
+/**
+ * Check if ESLint is running in Deno.
+ * @returns {boolean} `true` if the ESLint is running in Deno, `false` if it's not.
+ */
+function isRunningInDeno() {
+    return !!globalThis.Deno;
+}
+
 /**
  * Load the config array from the given filename.
  * @param {string} filePath The filename to load from.
+ * @param {boolean} hasUnstableTSConfigFlag `true` if the `unstable_ts_config` flag is enabled, `false` if it's not.
  * @returns {Promise<any>} The config loaded from the config file.
  */
-async function loadFlatConfigFile(filePath) {
+async function loadFlatConfigFile(filePath, hasUnstableTSConfigFlag) {
     debug(`Loading config from ${filePath}`);
 
     const fileURL = pathToFileURL(filePath);
 
     debug(`Config file URL is ${fileURL}`);
 
-    const mtime = (await fs.stat(filePath)).mtime.getTime();
+    const mtime = (await fs.stat(filePath)).mtime.getTime().toString();
 
     /*
      * Append a query with the config file's modification time (`mtime`) in order
@@ -314,7 +357,37 @@ async function loadFlatConfigFile(filePath) {
         delete require.cache[filePath];
     }
 
-    const config = (await import(fileURL)).default;
+    const isTS = isFileTS(filePath) && hasUnstableTSConfigFlag;
+
+    const isBun = isRunningInBun();
+
+    const isDeno = isRunningInDeno();
+
+    if (isTS && !isDeno && !isBun) {
+
+        const createJiti = await import("jiti").then(jitiModule => jitiModule.default, () => {
+            throw new Error("The 'jiti' library is required for loading TypeScript configuration files. Make sure to install it.");
+        });
+
+        /*
+         * Disabling `moduleCache` allows us to reload a
+         * config file when the last modified timestamp changes.
+         */
+
+        const jiti = createJiti(__filename, { moduleCache: false });
+
+        if (typeof jiti?.import !== "function") {
+            throw new Error("You are using an outdated version of the 'jiti' library. Please update to the latest version of 'jiti' to ensure compatibility and access to the latest features.");
+        }
+
+        const config = await jiti.import(fileURL.href);
+
+        importedConfigFileModificationTime.set(filePath, mtime);
+
+        return config?.default ?? config;
+    }
+
+    const config = (await import(fileURL.href)).default;
 
     importedConfigFileModificationTime.set(filePath, mtime);
 
@@ -326,11 +399,12 @@ async function loadFlatConfigFile(filePath) {
  * override config file was passed, and if so, using it; otherwise, as long
  * as override config file is not explicitly set to `false`, it will search
  * upwards from the cwd for a file named `eslint.config.js`.
- * @param {import("./eslint").ESLintOptions} options The ESLint instance options.
- * @returns {{configFilePath:string|undefined,basePath:string,error:Error|null}} Location information for
+ * @param {ESLintOptions} options The ESLint instance options.
+ * @param {boolean} hasUnstableTSConfigFlag `true` if the `unstable_ts_config` flag is enabled, `false` if it's not.
+ * @returns {Promise<{configFilePath:string|undefined;basePath:string;error:Error|null}>} Location information for
  *      the config file.
  */
-async function locateConfigFileToUse({ configFile, cwd }) {
+async function locateConfigFileToUse({ configFile, cwd }, hasUnstableTSConfigFlag) {
 
     // determine where to load config file from
     let configFilePath;
@@ -342,7 +416,7 @@ async function locateConfigFileToUse({ configFile, cwd }) {
         configFilePath = path.resolve(cwd, configFile);
     } else if (configFile !== false) {
         debug("Searching for eslint.config.js");
-        configFilePath = await findFlatConfigFile(cwd);
+        configFilePath = await findFlatConfigFile(cwd, hasUnstableTSConfigFlag);
 
         if (configFilePath) {
             basePath = path.resolve(path.dirname(configFilePath));
@@ -364,8 +438,8 @@ async function locateConfigFileToUse({ configFile, cwd }) {
 /**
  * Calculates the config array for this run based on inputs.
  * @param {ESLint} eslint The instance to create the config array for.
- * @param {import("./eslint").ESLintOptions} options The ESLint instance options.
- * @returns {FlatConfigArray} The config array for `eslint``.
+ * @param {ESLintOptions} options The ESLint instance options.
+ * @returns {Promise<typeof FlatConfigArray>} The config array for `eslint``.
  */
 async function calculateConfigArray(eslint, {
     cwd,
@@ -383,7 +457,9 @@ async function calculateConfigArray(eslint, {
         return slots.configs;
     }
 
-    const { configFilePath, basePath, error } = await locateConfigFileToUse({ configFile, cwd });
+    const hasUnstableTSConfigFlag = eslint.hasFlag("unstable_ts_config");
+
+    const { configFilePath, basePath, error } = await locateConfigFileToUse({ configFile, cwd }, hasUnstableTSConfigFlag);
 
     // config file is required to calculate config
     if (error) {
@@ -394,7 +470,7 @@ async function calculateConfigArray(eslint, {
 
     // load config file
     if (configFilePath) {
-        const fileConfig = await loadFlatConfigFile(configFilePath);
+        const fileConfig = await loadFlatConfigFile(configFilePath, hasUnstableTSConfigFlag);
 
         if (Array.isArray(fileConfig)) {
             configs.push(...fileConfig);
@@ -1144,7 +1220,7 @@ class ESLint {
 
             /**
              * The main formatter method.
-             * @param {LintResults[]} results The lint results to format.
+             * @param {LintResult[]} results The lint results to format.
              * @param {ResultsMeta} resultsMeta Warning count and max threshold.
              * @returns {string} The formatted lint results.
              */
@@ -1190,12 +1266,12 @@ class ESLint {
     /**
      * Finds the config file being used by this instance based on the options
      * passed to the constructor.
-     * @returns {string|undefined} The path to the config file being used or
+     * @returns {Promise<string|undefined>} The path to the config file being used or
      *      `undefined` if no config file is being used.
      */
     async findConfigFile() {
         const options = privateMembers.get(this).options;
-        const { configFilePath } = await locateConfigFileToUse(options);
+        const { configFilePath } = await locateConfigFileToUse(options, this.hasFlag("unstable_ts_config"));
 
         return configFilePath;
     }

@@ -9,7 +9,8 @@
  * @type {Map<string, string>}
  */
 const activeFlags = new Map([
-    ["test_only", "Used only for testing."]
+    ["test_only", "Used only for testing."],
+    ["unstable_ts_config", "Enable TypeScript configuration files."]
 ]);
 
 /**

@@ -132,6 +132,7 @@
     "globals": "^15.0.0",
     "got": "^11.8.3",
     "gray-matter": "^4.0.3",
+    "jiti": "^1.21.6",
     "js-yaml": "^4.1.0",
     "knip": "^5.21.0",
     "lint-staged": "^11.0.0",
@@ -165,6 +166,14 @@
     "webpack-cli": "^4.5.0",
     "yorkie": "^2.0.0"
   },
+  "peerDependencies": {
+    "jiti": "*"
+  },
+  "peerDependenciesMeta": {
+    "jiti": {
+      "optional": true
+    }
+  },
   "keywords": [
     "ast",
     "lint",