ESLint v9: Should ignoreTypeReferences Default to True for TypeScript Projects?

Answer

The intended default value for ignoreTypeReferences in ESLint v9's no-unused-vars rule is false. This preserves backward compatibility and keeps the rule strict for all files unless overridden.

Explanation vs. confirmed facts

Confirmed fact: The ESLint v9 documentation lists the option's default as false. Likely explanation: Keeping the default false avoids silently ignoring unused variables in JavaScript files where a variable might appear only in a type-like context (for example, JSDoc typedefs) or in a cast that is actually a value.

Steps to enable for TypeScript files only

1. Add an overrides block to your ESLint configuration targeting *.ts and *.tsx files.
2. Inside that block set ignoreTypeReferences: true while leaving the global default unchanged.
3. Example configuration:

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  rules: {
    'no-unused-vars': ['error', { args: 'none', vars: 'local', ignoreRestSiblings: false }]
  },
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      rules: {
        'no-unused-vars': ['error', { args: 'none', vars: 'local', ignoreRestSiblings: false, ignoreTypeReferences: true }]
      }
    }
  ]
};

Verification

Run the following command on a sample TypeScript file to see the effective config:

npx eslint --print-config src/example.ts | grep -A2 -B2 'no-unused-vars'

You should observe ignoreTypeReferences: false in the global config and ignoreTypeReferences: true only within the overrides section.

Recommendation

Do not change the global default to true. Instead, use an overrides block to enable ignoreTypeReferences for TypeScript files only, keeping JavaScript checking strict. If you are unsure whether your codebase contains any JavaScript files that might be affected, run the verification step above on a representative sample before applying the override.