d-subrahmanyam/eslint-biome

ESLint 9 & Biome Linting

When NOT to Use This Skill

• Legacy ESLint (.eslintrc) - Use eslint skill for old config format
• TypeScript-only rules - Use typescript-eslint skill for deep TypeScript linting
• Java/Kotlin linting - Use sonarqube skill
• Code quality principles - Use quality-common for SOLID/Clean Code

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: eslint or biome for comprehensive documentation.

Official References

| Tool | Documentation | |------|---------------| | ESLint 9 | https://eslint.org/docs/latest/ | | typescript-eslint | https://typescript-eslint.io/ | | Biome | https://biomejs.dev/ | | ESLint Rules | https://eslint.org/docs/latest/rules/ | | Biome Rules | https://biomejs.dev/linter/rules/ |

---

ESLint 9 Flat Config

Basic Setup

npm install --save-dev eslint @eslint/js typescript typescript-eslint

// eslint.config.mjs
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
);

TypeScript with Type Checking

// eslint.config.mjs
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

Full Configuration Example

// eslint.config.mjs
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactPlugin from 'eslint-plugin-react';
import reactHooksPlugin from 'eslint-plugin-react-hooks';

export default tseslint.config(
  // Ignores
  {
    ignores: ['dist/**', 'node_modules/**', '*.config.js'],
  },

  // Base configs
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,

  // TypeScript files
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Prevent bugs
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/await-thenable': 'error',

      // Code quality
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/explicit-function-return-type': 'warn',
      '@typescript-eslint/consistent-type-imports': 'error',

      // Complexity
      'complexity': ['warn', 10],
      'max-depth': ['warn', 4],
      'max-lines-per-function': ['warn', 50],
    },
  },

  // React files
  {
    files: ['**/*.tsx'],
    plugins: {
      react: reactPlugin,
      'react-hooks': reactHooksPlugin,
    },
    rules: {
      ...reactPlugin.configs.recommended.rules,
      ...reactHooksPlugin.configs.recommended.rules,
      'react/react-in-jsx-scope': 'off',
    },
    settings: {
      react: { version: 'detect' },
    },
  },

  // Test files
  {
    files: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
      'max-lines-per-function': 'off',
    },
  },
);

---

typescript-eslint Presets

| Preset | Description | |--------|-------------| | recommended | Core rules without type checking | | recommendedTypeChecked | Recommended + type-aware rules | | strict | All recommended + stricter rules | | strictTypeChecked | Strict + type-aware rules | | stylistic | Style/convention rules | | stylisticTypeChecked | Stylistic + type-aware |

Key Type-Checked Rules

rules: {
  // Async/Promise safety
  '@typescript-eslint/no-floating-promises': 'error',
  '@typescript-eslint/no-misused-promises': 'error',
  '@typescript-eslint/await-thenable': 'error',
  '@typescript-eslint/require-await': 'error',

  // Type safety
  '@typescript-eslint/no-unsafe-argument': 'error',
  '@typescript-eslint/no-unsafe-assignment': 'error',
  '@typescript-eslint/no-unsafe-call': 'error',
  '@typescript-eslint/no-unsafe-member-access': 'error',
  '@typescript-eslint/no-unsafe-return': 'error',

  // Best practices
  '@typescript-eslint/no-unnecessary-condition': 'error',
  '@typescript-eslint/prefer-nullish-coalescing': 'error',
  '@typescript-eslint/prefer-optional-chain': 'error',
}

---

Biome

Installation

npm install --save-dev @biomejs/biome
npx @biomejs/biome init

Configuration (biome.json)

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": { "maxAllowedComplexity": 15 }
        }
      },
      "correctness": {
        "noUnusedImports": "error",
        "noUnusedVariables": "error",
        "useExhaustiveDependencies": "warn"
      },
      "suspicious": {
        "noExplicitAny": "error",
        "noConsoleLog": "warn"
      },
      "style": {
        "useConst": "error",
        "noNonNullAssertion": "warn"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "always"
    }
  }
}

Rule Categories

| Category | Rules | Description | |----------|-------|-------------| | a11y | 40+ | Accessibility problems | | complexity | 15+ | Code simplification | | correctness | 60+ | Guaranteed errors | | performance | 10+ | Efficiency improvements | | security | 5+ | Security flaws | | style | 50+ | Consistent code style | | suspicious | 50+ | Likely incorrect patterns | | nursery | 100+ | Experimental rules |

Commands

# Check all
npx biome check .

# Fix auto-fixable issues
npx biome check --write .

# Lint only
npx biome lint .

# Format only
npx biome format --write .

# CI mode (no writes)
npx biome ci .

---

Migration: ESLint to Biome

# Automatic migration
npx @biomejs/biome migrate eslint --write

# With inspired rules
npx @biomejs/biome migrate eslint --include-inspired --write

# Migrate prettier config too
npx @biomejs/biome migrate prettier --write

Supported ESLint Plugins

| Plugin | Biome Support | |--------|---------------| | @typescript-eslint | Full | | eslint-plugin-react | Full | | eslint-plugin-react-hooks | Full | | eslint-plugin-jsx-a11y | Full | | eslint-plugin-unicorn | Partial | | eslint-plugin-import | Partial |

Rule Name Mapping

| ESLint | Biome | |--------|-------| | no-unused-vars | noUnusedVariables | | no-console | noConsoleLog | | prefer-const | useConst | | @typescript-eslint/no-explicit-any | noExplicitAny |

---

ESLint vs Biome

| Feature | ESLint 9 | Biome | |---------|----------|-------| | Speed | ~3-5s/10k lines | ~200ms/10k lines | | Config | JavaScript | JSON/JSONC | | Plugins | 1000+ | Built-in only | | Formatter | Needs Prettier | Built-in | | Type-aware | Full support | ~85% coverage | | Languages | JS/TS + plugins | JS/TS/JSON/CSS |

When to Use ESLint

• Need specific plugins (import sorting, testing rules)
• Require full type-aware linting
• Have complex dynamic configuration

When to Use Biome

• Speed is critical (large codebase, CI)
• Want unified linting + formatting
• Don't need extensive plugin ecosystem

---

CI Integration

ESLint (GitHub Actions)

- name: Lint
  run: npx eslint . --max-warnings=0

# With caching
- name: Lint with cache
  run: npx eslint . --cache --cache-location node_modules/.cache/eslint

Biome (GitHub Actions)

- name: Setup Biome
  uses: biomejs/setup-biome@v2
  with:
    version: latest

- name: Run Biome
  run: biome ci .

---

Checklist

ESLint Setup

• [ ] Using flat config (eslint.config.mjs)
• [ ] Type-checked rules enabled
• [ ] No deprecated eslintrc format
• [ ] Strict TypeScript rules
• [ ] CI caching configured

Biome Setup

• [ ] biome.json configured
• [ ] Recommended rules enabled
• [ ] Formatter settings match team style
• [ ] CI mode in pipeline

Metrics

| Metric | Target | |--------|--------| | Lint warnings | 0 | | Lint errors | 0 | | Type coverage | > 95% | | Lint time (CI) | < 30s |

---

Anti-Patterns

| Anti-Pattern | Why It's Bad | Correct Approach | |--------------|--------------|------------------| | Using ESLint without type checking | Misses 50% of TS issues | Use recommendedTypeChecked | | Biome + ESLint both linting same files | Duplicate work, conflicts | Choose one per file type | | No ignores in flat config | Lints dist/, node_modules/ | Add ignores at top of config | | Type checking all JS files | Slow, JS has no types | Limit to **/*.ts files only | | Not using Biome CI mode | Different results locally vs CI | Use biome ci . in pipelines | | Mixing .eslintrc and flat config | Confusing, deprecated pattern | Migrate fully to flat config |

Quick Troubleshooting

| Issue | Likely Cause | Solution | |-------|--------------|----------| | ESLint not finding types | projectService not enabled | Add projectService: true to parserOptions | | Biome migration creates 1000+ errors | Stricter rules than ESLint | Use --write to auto-fix, adjust rules | | Linting takes 2+ minutes | Type checking entire codebase | Use files: ['**/*.ts'] for type rules | | Biome doesn't support plugin X | Limited plugin ecosystem | Stick with ESLint or find alternative | | Flat config not recognized | Wrong file name | Must be eslint.config.mjs (not .js) | | Rules overriding each other | Order in config array | Later configs override earlier ones |

---

Related Skills

• TypeScript
• Quality Principles
• GitHub Actions