or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

ESLint Define Config

ESLint Define Config provides typed utility functions for ESLint configuration files, offering IntelliSense, type checking, documentation, and deprecation warnings. It supports both traditional .eslintrc.js files and modern flat eslint.config.js configurations without adding runtime dependencies.

Package Information

Package Name: eslint-define-config
Package Type: npm
Language: TypeScript
Installation: npm install --save-dev eslint-define-config

Core Imports

import { defineConfig, defineFlatConfig } from "eslint-define-config";

For CommonJS:

const { defineConfig, defineFlatConfig } = require("eslint-define-config");

Basic Usage

Traditional ESLint Configuration (.eslintrc.js):

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

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

module.exports = defineConfig({
  root: true,
  env: {
    node: true,
    es2021: true,
  },
  extends: ['eslint:recommended'],
  parserOptions: {
    ecmaVersion: 2021,
    sourceType: 'module',
  },
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error',
  },
});

Flat ESLint Configuration (eslint.config.js):

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

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

module.exports = defineFlatConfig([
  'eslint:recommended',
  {
    languageOptions: {
      ecmaVersion: 2021,
      sourceType: 'module',
    },
    rules: {
      'no-console': 'warn',
      'no-unused-vars': 'error',
    },
  },
]);

Architecture

ESLint Define Config is built around several key concepts:

Identity Functions: Both defineConfig and defineFlatConfig are identity functions that return the input unchanged, providing compile-time benefits only
Type Safety: Comprehensive TypeScript definitions for all ESLint configuration options and 300+ core ESLint rules
Plugin Extensibility: Module augmentation support allowing ESLint plugins to extend rule definitions
Zero Runtime Impact: No dependencies or runtime code, purely for development-time type checking and IntelliSense
Dual Configuration Support: Handles both legacy and modern ESLint configuration formats

Capabilities

Traditional Configuration

Define typed ESLint configurations for .eslintrc.js files with comprehensive type checking.

/**
 * Define an ESLint config.
 * @param config ESLint config.
 * @returns ESLint config.
 */
function defineConfig(config: ESLintConfig): ESLintConfig;

interface ESLintConfig {
  /** Whether this is the root config */
  root?: boolean;
  /** Patterns to ignore during linting */
  ignorePatterns?: string[];
  /** Environment settings providing predefined global variables */
  env?: Environments;
  /** Configuration files to extend */
  extends?: Extends;
  /** Global variables specification */
  globals?: Record<string, 'readonly' | 'writable' | false | 'readable' | true | 'writeable' | 'off'>;
  /** Parser to use for parsing files */
  parser?: Parser;
  /** Parser-specific options */
  parserOptions?: ParserOptions;
  /** Plugins that define additional rules, environments, configs, etc. */
  plugins?: Plugin[];
  /** Processor for transforming files before linting */
  processor?: string;
  /** ESLint rules configuration */
  rules?: Partial<Rules>;
  /** Override configurations for specific file patterns */
  overrides?: Overrides;
  /** Shared settings available to all rules */
  settings?: Settings;
  /** Disable inline ESLint comments */
  noInlineConfig?: boolean;
  /** Report unused eslint-disable comments */
  reportUnusedDisableDirectives?: boolean;
}

Flat Configuration

Define typed ESLint configurations for modern eslint.config.js files with support for both single objects and arrays.

/**
 * Define an item of Flat ESLint config.
 * @param config an item of Flat ESLint config.
 * @returns an item of Flat ESLint config.
 */
function defineFlatConfig(config: FlatESLintConfig): FlatESLintConfig;

/**
 * Define a flat ESLint config.
 * @param config Flat ESLint config.
 * @returns Flat ESLint config.
 */
function defineFlatConfig(config: ReadonlyArray<FlatESLintConfig>): FlatESLintConfig[];

interface FlatESLintConfig {
  /** Glob patterns indicating files the configuration applies to */
  files?: string[];
  /** Glob patterns indicating files the configuration should not apply to */
  ignores?: string[];
  /** Language-specific configuration options */
  languageOptions?: LanguageOptions;
  /** Linter-specific options */
  linterOptions?: LinterOptions;
  /** Processor for file transformation before linting */
  processor?: string | Linter.Processor;
  /** Plugin name-to-object mapping */
  plugins?: Record<string, ESLint.Plugin>;
  /** ESLint rules configuration */
  rules?: Partial<Rules>;
  /** Shared settings available to all rules */
  settings?: Record<string, any>;
}

Language Options

Language-specific configuration for flat ESLint configurations.

interface LanguageOptions {
  /** ECMAScript version to parse (default: "latest") */
  ecmaVersion?: EcmaVersion;
  /** Global variables available in the environment */
  globals?: Record<string, 'readonly' | 'writable' | false | 'readable' | true | 'writeable' | 'off'>;
  /** Parser to use for parsing files */
  parser?: Parser | ParserModule;
  /** Parser-specific options */
  parserOptions?: ParserOptions;
  /** Source type: script, module, or commonjs */
  sourceType?: SourceType | 'commonjs';
}

interface LinterOptions {
  /** Boolean indicating if inline configuration is allowed */
  noInlineConfig?: boolean;
  /** Boolean indicating if unused disable directives should be tracked and reported */
  reportUnusedDisableDirectives?: boolean;
}

type ParserModule = {
  parse(text: string, options?: any): any;
} | {
  parseForESLint(text: string, options?: any): any;
};

Parser Configuration

Parser and parsing options for both traditional and flat configurations.

type Parser = string | { parse: Function; parseForESLint: Function };

interface ParserOptions {
  /** ECMAScript version number */
  ecmaVersion?: EcmaVersion;
  /** Source type: script or module */
  sourceType?: SourceType;
  /** Additional language features to enable */
  ecmaFeatures?: EcmaFeatures;
  /** Additional parser-specific options */
  [key: string]: any;
}

type EcmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 'latest';

type SourceType = 'script' | 'module';

interface EcmaFeatures extends Partial<Record<string, boolean>> {
  /** Allow return statements in global scope */
  globalReturn?: boolean;
  /** Enable global strict mode */
  impliedStrict?: boolean;
  /** Enable JSX parsing */
  jsx?: boolean;
  /** Enable experimental object rest/spread properties */
  experimentalObjectRestSpread?: boolean;
}

Rule System

Comprehensive rule system with type safety for all ESLint core rules and plugin extensibility.

interface Rules extends CustomRules, EslintRules, Record<string, RuleConfig> {}

/** Extensible interface for custom rules from plugins */
interface CustomRuleOptions {}

type CustomRules = {
  [TRuleName in keyof CustomRuleOptions]: RuleConfig<CustomRuleOptions[TRuleName]>;
};

type RuleConfig<TOptions = any> = 
  | RuleSeverity 
  | [RuleSeverity, ...TOptions[]]
  | [RuleSeverity, TOptions];

type RuleSeverity = 'off' | 'warn' | 'error' | 0 | 1 | 2;

Plugin Extensibility

Support for extending rule definitions through module augmentation.

// Plugin authors can extend CustomRuleOptions like:
declare module 'eslint-define-config' {
  export interface CustomRuleOptions {
    '@typescript-eslint/array-type': [
      {
        default?: 'array' | 'generic' | 'array-simple';
        readonly?: 'array' | 'generic' | 'array-simple';
      },
    ];
  }
}

Type Definitions

Environment Types

interface Environments extends Partial<Record<string, boolean>> {
  /** Browser global variables */
  browser?: boolean;
  /** Node.js global variables */
  node?: boolean;
  /** CommonJS global variables */
  commonjs?: boolean;
  /** Shared Node.js and Browser globals */
  'shared-node-browser'?: boolean;
  /** Web Workers global variables */
  worker?: boolean;
  /** AMD global variables */
  amd?: boolean;
  /** Mocha global variables */
  mocha?: boolean;
  /** Jasmine global variables */
  jasmine?: boolean;
  /** Jest global variables */
  jest?: boolean;
  /** PhantomJS global variables */
  phantomjs?: boolean;
  /** Protractor global variables */
  protractor?: boolean;
  /** QUnit global variables */
  qunit?: boolean;
  /** jQuery global variables */
  jquery?: boolean;
  /** Prototypejs global variables */
  prototypejs?: boolean;
  /** ShellJS global variables */
  shelljs?: boolean;
  /** Meteor global variables */
  meteor?: boolean;
  /** Mongo global variables */
  mongo?: boolean;
  /** AppleScript global variables */
  applescript?: boolean;
  /** NasHorn global variables */
  nashorn?: boolean;
  /** ServiceWorker global variables */
  serviceworker?: boolean;
  /** Atomtest global variables */
  atomtest?: boolean;
  /** Embertest global variables */
  embertest?: boolean;
  /** WebExtensions global variables */
  webextensions?: boolean;
  /** Greasemonkey global variables */
  greasemonkey?: boolean;
  /** ES6 global variables */
  es6?: boolean;
  /** ES2017 global variables */
  es2017?: boolean;
  /** ES2020 global variables */
  es2020?: boolean;
  /** ES2021 global variables */
  es2021?: boolean;
  /** ES2022 global variables */
  es2022?: boolean;
}

Extension Types

type Extends = string | string[];
type Plugin = string;
type Overrides = Override[];

interface Override {
  files: string | string[];
  excludedFiles?: string | string[];
  env?: Environments;
  extends?: Extends;
  globals?: Record<string, boolean | 'readonly' | 'writable' | 'off'>;
  parser?: Parser;
  parserOptions?: ParserOptions;
  plugins?: Plugin[];
  processor?: string;
  rules?: Partial<Rules>;
  settings?: Settings;
}

Settings Types

interface Settings extends Partial<Record<string, any>> {
  /** Import resolver settings */
  'import/resolver'?: any;
  /** Import/core modules */
  'import/core-modules'?: string[];
  /** Import/external module folders */
  'import/external-module-folders'?: string[];
  /** React version detection */
  react?: {
    createClass?: string;
    pragma?: string;
    fragment?: string;
    version?: string;
    flowVersion?: string;
  };
  /** JSX pragma for non-React JSX */
  linkComponents?: string[];
  /** Prop types */
  propWrapperFunctions?: string[];
  /** Component detection */
  componentWrapperFunctions?: string[];
  /** Form components */
  formComponents?: string[];
}

Utility Types

/**
 * A literal type that supports custom further strings but preserves autocompletion in IDEs.
 *
 * @see [copied from issue](https://github.com/microsoft/TypeScript/issues/29729#issuecomment-471566609)
 */
type LiteralUnion<TUnion extends TBase, TBase = string> = 
  | TUnion 
  | (TBase & { zz_IGNORE_ME?: never });

Error Handling

ESLint Define Config functions are identity functions that perform no runtime validation. Type errors are caught at compile-time by TypeScript. Common error patterns:

Invalid rule names: TypeScript will show autocompletion for valid rule names
Invalid rule options: TypeScript validates rule option types and structures
Missing required properties: TypeScript enforces required configuration properties
Type mismatches: Parser options, environment settings, and other configurations are fully typed

Usage Patterns

Development Workflow

Install the package as a development dependency
Add TypeScript reference comments for additional plugin types
Use // @ts-check at the top of JavaScript config files
Configure your IDE to show TypeScript errors in JavaScript files
Leverage autocompletion and documentation on hover

Plugin Integration

ESLint plugins can extend the rule definitions by declaring module augmentation:

// In plugin package.json types file
declare module 'eslint-define-config' {
  export interface CustomRuleOptions {
    'my-plugin/my-rule': [
      {
        option1?: string;
        option2?: boolean;
      }
    ];
  }
}

IDE Integration

The package provides optimal experience in IDEs that support TypeScript:

VSCode: Full IntelliSense with rule documentation
WebStorm: Auto-completion and type checking
Vim/Neovim: Via TypeScript language server
Emacs: Via TypeScript language server