eslint-define-config

To use eslint-define-config for type-safe ESLint configurations, add both eslint and eslint-define-config to your project's development dependencies using your preferred package manager.

# npm
npm add --save-dev eslint eslint-define-config

# yarn
yarn add --dev eslint eslint-define-config

# pnpm
pnpm add --save-dev eslint eslint-define-config

The Settings interface represents the object used to define ESLint settings. It is composed of two parts:

1. CustomSettings: An interface that can be extended by other packages (like plugins) to add specific, typed configuration keys.
2. Partial<Record<string, unknown>>: A fallback that allows any arbitrary string key with an unknown value, ensuring compatibility with existing ESLint settings that haven't been explicitly typed.

For the new ESLint Flat Config format (eslint.config.js), use the defineFlatConfig function. Similar to the legacy format, use // @ts-check at the top of the file to enable type checking. You can pass an array of configuration objects, including recommended configs from plugins and your own custom configurations.

// @ts-check
const { defineFlatConfig } = require('eslint-define-config');
const js = require('@eslint/js');
const customConfig = require('./custom-config.js');

/// <reference types="@eslint-types/typescript-eslint" />

module.exports = defineFlatConfig([
  js.configs.recommended,
  customConfig,
  {
    plugins: {
      // plugins...
    },
    rules: {
      // rules...
    },
  },
]);

If you are a plugin author or want to add support for a plugin, you can extend the eslint-define-config module by declaring a module augmentation. This allows you to provide type definitions for custom rules, extending the following interfaces:

• CustomRuleOptions (for rule configuration shapes)
• CustomExtends
• CustomParserOptions
• CustomParsers
• CustomPlugins
• CustomSettings

declare module 'eslint-define-config' {
  export interface CustomRuleOptions {
    /**
     * Require consistently using either `T[]` or `Array<T>` for arrays.
     *
     * @see [array-type](https://typescript-eslint.io/rules/array-type)
     */
    '@typescript-eslint/array-type': [
      { 
        default?: 'array' | 'generic' | 'array-simple';
        readonly?: 'array' | 'generic' | 'array-simple';
      },
    ];

    // ... more Rules
  }
}

For legacy .eslintrc.js configuration files, use the defineConfig function. To enable type checking and auto-suggestions, include // @ts-check at the top of the file. You can also add type references for specific plugins (e.g., @eslint-types/typescript-eslint) using Triple-Slash Directives to enable rule auto-suggestions for those plugins.

// @ts-check
const { defineConfig } = require('eslint-define-config');

/// <reference types="@eslint-types/typescript-eslint" />

module.exports = defineConfig({
  root: true,
  rules: {
    // rules...
  },
});

If you are developing a plugin (like @typescript-eslint/eslint-plugin) and want to add custom options to the parserOptions object in eslint-define-config, you can use module augmentation on the CustomParserOptions interface.

Example of adding TypeScript-specific options:

import 'eslint-define-config';

declare module 'eslint-define-config' {
  export interface CustomParserOptions {
    tsconfigRootDir?: string;
    useJSXTextNode?: boolean;
    warnOnUnsupportedTypeScriptVersion?: boolean;
    emitDecoratorMetadata?: boolean;
  }
}

The ESLintConfig interface provides type definitions for the legacy ESLint configuration object. Use this interface when you need to type a configuration object that follows the traditional ESLint configuration format (e.g., .eslintrc.js).

import type { ESLintConfig } from 'eslint-define-config/config';

const config: ESLintConfig = {
  root: true,
  env: { browser: true, es2021: true },
  extends: ['eslint:recommended'],
  parserOptions: { ecmaVersion: 'latest' },
  rules: {
    'no-unused-vars': 'error'
  }
};

The ecmaVersion option in ParserOptions specifies the version of ECMAScript syntax to use. This affects how the parser performs scope analysis.

Valid values include:

• A version number (e.g., 3, 5, 6, 14)
• A year (e.g., 2015, 2023)
• 'latest'

Note: When using a version or a year, the value must be a number (or the string 'latest'); do not include the es prefix (e.g., use 2015, not es2015).

@default 2018

// Example usage in an ESLint config
export default [{
  languageOptions: {
    parserOptions: {
      ecmaVersion: 2023,
    },
  },
}];

The CustomExtends interface is a special extension point that allows other packages (such as ESLint plugins) to register their own configuration strings as valid values for the extends property. By declaring a module augmentation for eslint-define-config, a plugin can ensure that its specific configuration presets (e.g., 'plugin:@typescript-eslint/recommended') are recognized by TypeScript when using eslint-define-config in a project.

// Example of how a plugin like @typescript-eslint would declare custom extensions
declare module 'eslint-define-config' {
  export interface CustomExtends {
    'plugin:@typescript-eslint/all': void;
    'plugin:@typescript-eslint/base': void;
    'plugin:@typescript-eslint/recommended': void;
    // ... other presets
  }
}

The sourceType option determines how the parser treats your code files.

• 'script' (default): Standard JavaScript scripts.
• 'module': ECMAScript modules (ESM).

@default 'script'

// Example usage in an ESLint config
export default [{
  languageOptions: {
    parserOptions: {
      sourceType: 'module',
    },
  },
}];

The ecmaFeatures object allows you to enable specific additional language features. It extends a partial record of strings to booleans, but includes several well-known options:

• globalReturn: Allow return statements in the global scope.
• impliedStrict: Enable global strict mode (if ecmaVersion is 5 or greater).
• jsx: Enable JSX.

// Example usage in an ESLint config
export default [{
  languageOptions: {
    parserOptions: {
      ecmaFeatures: {
        jsx: true,
        impliedStrict: true,
      },
    },
  },
}];

The package re-exports all relevant types for ESLint configuration. You can import these types directly to use them in your own functions or type definitions:

• ESLintConfig: Types for standard ESLint configuration.
• FlatESLintConfig: Types for the new Flat Config format.
• ParserOptions: Types for parser-specific options.
• Rules: Types for ESLint rules.

import type { ESLintConfig, FlatESLintConfig } from 'eslint-define-config';