eslint-config

Original source / Raw SKILL.md

---
name: eslint-config
# prettier-ignore
description: Use when configuring ESLint - covers flat config, TypeScript integration, and custom rules
---

# ESLint Configuration Best Practices

## Quick Start (Flat Config)

```javascript
// eslint.config.js
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["src/**/*.ts"],
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
    },
  },
  {
    ignores: ["dist/", "node_modules/"],
  }
);
```

## Core Configuration

### TypeScript Integration

```javascript
import tseslint from "typescript-eslint";

export default tseslint.config(
  ...tseslint.configs.strictTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
  }
);
```

### Custom Rules

```javascript
{
  rules: {
    // Disallow console in production
    "no-console": "warn",

    // Require explicit return types
    "@typescript-eslint/explicit-function-return-type": "error",

    // Prefer const
    "prefer-const": "error",

    // No floating promises
    "@typescript-eslint/no-floating-promises": "error",
  }
}
```

### File-Specific Rules

```javascript
export default [
  {
    files: ["src/**/*.ts"],
    rules: { /* production rules */ }
  },
  {
    files: ["**/*.test.ts", "__tests__/**/*.ts"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-non-null-assertion": "off",
    }
  },
  {
    files: ["scripts/**/*.ts"],
    rules: {
      "no-console": "off",
    }
  }
];
```

## Common Patterns for Language Projects

### Parser/Interpreter Specific

```javascript
{
  rules: {
    // Allow switch fallthrough for token parsing
    "no-fallthrough": ["error", { commentPattern: "falls?\\s*through" }],

    // Allow bitwise for flags
    "no-bitwise": "off",

    // Complex functions in interpreters
    "complexity": ["warn", 20],
    "max-depth": ["warn", 5],
  }
}
```

### Naming Conventions

```javascript
{
  rules: {
    "@typescript-eslint/naming-convention": [
      "error",
      { selector: "interface", format: ["PascalCase"] },
      { selector: "typeAlias", format: ["PascalCase"] },
      { selector: "enum", format: ["PascalCase"] },
      { selector: "enumMember", format: ["UPPER_CASE"] },
    ]
  }
}
```

## Migration from Legacy Config

```javascript
// Old: .eslintrc.json
{
  "extends": ["eslint:recommended"],
  "rules": { "semi": "error" }
}

// New: eslint.config.js
import eslint from "@eslint/js";
export default [
  eslint.configs.recommended,
  { rules: { semi: "error" } }
];
```

## Scripts

```json
{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}
```

## Reference Files

- [references/rules.md](references/rules.md) - Common rule configurations
- [references/plugins.md](references/plugins.md) - Popular plugins


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/rules.md

```markdown
# Common Rule Configurations

## Code Quality

```javascript
{
  rules: {
    // Enforce consistent code style
    "prefer-const": "error",
    "no-var": "error",
    "eqeqeq": ["error", "always"],

    // Prevent errors
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": ["error", {
      argsIgnorePattern: "^_",
      varsIgnorePattern: "^_",
    }],

    // Code complexity
    "complexity": ["warn", 15],
    "max-depth": ["warn", 4],
    "max-lines-per-function": ["warn", { max: 100 }],
  }
}
```

## TypeScript Specific

```javascript
{
  rules: {
    // Type safety
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-non-null-assertion": "warn",
    "@typescript-eslint/strict-boolean-expressions": "error",

    // Async/Promise handling
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/await-thenable": "error",
    "@typescript-eslint/no-misused-promises": "error",

    // Consistency
    "@typescript-eslint/consistent-type-imports": "error",
    "@typescript-eslint/consistent-type-definitions": ["error", "interface"],

    // Return types
    "@typescript-eslint/explicit-function-return-type": ["error", {
      allowExpressions: true,
      allowTypedFunctionExpressions: true,
    }],
  }
}
```

## Naming Conventions

```javascript
{
  rules: {
    "@typescript-eslint/naming-convention": [
      "error",
      // Interfaces
      { selector: "interface", format: ["PascalCase"] },

      // Type aliases
      { selector: "typeAlias", format: ["PascalCase"] },

      // Enums
      { selector: "enum", format: ["PascalCase"] },
      { selector: "enumMember", format: ["UPPER_CASE"] },

      // Variables
      { selector: "variable", format: ["camelCase", "UPPER_CASE"] },
      { selector: "variable", modifiers: ["const"], format: ["camelCase", "UPPER_CASE", "PascalCase"] },

      // Parameters
      { selector: "parameter", format: ["camelCase"], leadingUnderscore: "allow" },

      // Private members
      { selector: "memberLike", modifiers: ["private"], format: ["camelCase"], leadingUnderscore: "require" },
    ],
  }
}
```

## Import Rules

```javascript
{
  rules: {
    // Import order
    "import/order": ["error", {
      groups: ["builtin", "external", "internal", "parent", "sibling", "index"],
      "newlines-between": "always",
      alphabetize: { order: "asc" },
    }],

    // No default exports
    "import/prefer-default-export": "off",
    "import/no-default-export": "error",

    // Circular dependencies
    "import/no-cycle": "error",
  }
}
```

## Language Interpreter Specific

```javascript
{
  rules: {
    // Allow switch fallthrough for token parsing
    "no-fallthrough": ["error", {
      commentPattern: "falls?\\s*through",
    }],

    // Allow bitwise for flags
    "no-bitwise": "off",

    // Complex functions in interpreters
    "complexity": ["warn", 25],
    "max-depth": ["warn", 6],

    // Large switch statements for AST
    "max-lines-per-function": ["warn", { max: 200 }],
  }
}
```

## Disabling Rules

```javascript
// Inline disable
/* eslint-disable @typescript-eslint/no-explicit-any */
const value: any = something;
/* eslint-enable @typescript-eslint/no-explicit-any */

// Single line
const value: any = something; // eslint-disable-line

// Next line
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const value: any = something;
```

```

### references/plugins.md

```markdown
# Popular ESLint Plugins

## TypeScript

### typescript-eslint

The essential TypeScript integration.

```bash
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin
```

```javascript
import tseslint from "typescript-eslint";

export default tseslint.config(
  ...tseslint.configs.recommended,
  // Or stricter
  ...tseslint.configs.strictTypeChecked,
);
```

## Import Management

### eslint-plugin-import

Import/export linting.

```bash
npm install -D eslint-plugin-import
```

```javascript
import importPlugin from "eslint-plugin-import";

export default [
  importPlugin.flatConfigs.recommended,
  {
    rules: {
      "import/order": "error",
      "import/no-cycle": "error",
    },
  },
];
```

## Testing

### eslint-plugin-jest

Jest-specific rules.

```bash
npm install -D eslint-plugin-jest
```

```javascript
import jest from "eslint-plugin-jest";

export default [
  {
    files: ["**/*.test.ts"],
    ...jest.configs["flat/recommended"],
  },
];
```

## Node.js

### eslint-plugin-n

Node.js specific rules.

```bash
npm install -D eslint-plugin-n
```

```javascript
import n from "eslint-plugin-n";

export default [
  n.configs["flat/recommended"],
  {
    rules: {
      "n/no-missing-import": "error",
      "n/no-unsupported-features/es-syntax": "off",
    },
  },
];
```

## Prettier Integration

### eslint-config-prettier

Disables conflicting rules.

```bash
npm install -D eslint-config-prettier
```

```javascript
import prettier from "eslint-config-prettier";

export default [
  // Your rules...
  prettier, // Must be last
];
```

## Unicorn

### eslint-plugin-unicorn

Various powerful rules.

```bash
npm install -D eslint-plugin-unicorn
```

```javascript
import unicorn from "eslint-plugin-unicorn";

export default [
  unicorn.configs["flat/recommended"],
  {
    rules: {
      "unicorn/prevent-abbreviations": "off",
      "unicorn/no-null": "off",
    },
  },
];
```

## Security

### eslint-plugin-security

Security-focused rules.

```bash
npm install -D eslint-plugin-security
```

```javascript
import security from "eslint-plugin-security";

export default [
  security.configs.recommended,
];
```

## JSDoc

### eslint-plugin-jsdoc

JSDoc comment validation.

```bash
npm install -D eslint-plugin-jsdoc
```

```javascript
import jsdoc from "eslint-plugin-jsdoc";

export default [
  jsdoc.configs["flat/recommended-typescript"],
];
```

## Complete Example

```javascript
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
import importPlugin from "eslint-plugin-import";
import jest from "eslint-plugin-jest";
import prettier from "eslint-config-prettier";

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  importPlugin.flatConfigs.recommended,
  {
    files: ["**/*.test.ts"],
    ...jest.configs["flat/recommended"],
  },
  prettier,
);
```

```