📘 ESLint with TypeScript: Linting Setup

🎯 Introduction

Welcome to the world of clean, beautiful TypeScript code! 🎉 In this comprehensive guide, we’ll explore how to set up ESLint with TypeScript to catch errors, enforce consistent coding standards, and make your code shine.

Think of ESLint as your friendly code companion 🤖 that helps you write better TypeScript by pointing out potential issues, style inconsistencies, and suggesting improvements. Whether you’re building web applications 🌐, APIs 🖥️, or libraries 📚, proper linting setup is essential for maintainable, professional code.

By the end of this tutorial, you’ll have a rock-solid ESLint configuration that makes your TypeScript development experience smooth and enjoyable! Let’s dive in! 🏊‍♂️

📚 Understanding ESLint with TypeScript

🤔 What is ESLint?

ESLint is like having a super-smart proofreader 📝 for your code! Think of it as a spell checker that not only finds typos but also suggests better ways to write sentences (in this case, code).

In TypeScript terms, ESLint analyzes your code and:

✨ Catches potential bugs before they reach production
🚀 Enforces consistent coding style across your team
🛡️ Identifies code quality issues and anti-patterns
📖 Provides helpful suggestions for improvement

💡 Why Use ESLint with TypeScript?

Here’s why developers love this powerful combination:

Double Protection 🔒: TypeScript catches type errors, ESLint catches everything else
Team Consistency 💻: Everyone writes code the same way
Early Bug Detection 🐛: Find issues before they become problems
Learning Aid 📚: ESLint teaches you better coding practices
Automated Fixes 🔧: Many issues can be auto-fixed

Real-world example: Imagine building a shopping app 🛒. ESLint will catch unused variables, suggest better naming conventions, and ensure your code follows best practices while TypeScript handles the type safety!

🔧 Basic Setup and Installation

📦 Installing ESLint and TypeScript Support

Let’s start by setting up our linting toolkit:

# 📦 Install ESLint and TypeScript parser
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# 🚀 Or with yarn
yarn add --dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# ⚡ Or with pnpm
pnpm add --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

💡 What we just installed:

eslint: The core ESLint engine 🏭
@typescript-eslint/parser: Teaches ESLint to understand TypeScript 🧠
@typescript-eslint/eslint-plugin: TypeScript-specific rules and fixes ⚙️

🎯 Basic Configuration File

Create your .eslintrc.js file:

// 👋 Hello, ESLint configuration!
module.exports = {
  // 🎨 Tell ESLint this is the root config
  root: true,
  
  // 🧠 Use TypeScript parser
  parser: '@typescript-eslint/parser',
  
  // ⚙️ Parser options
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
    project: './tsconfig.json', // 📍 Point to your TypeScript config
  },
  
  // 🔌 Enable TypeScript plugin
  plugins: ['@typescript-eslint'],
  
  // 📋 Extend recommended configurations
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
  ],
  
  // 🏠 Environment settings
  env: {
    node: true,
    browser: true,
    es2020: true,
  },
};

💡 Practical Examples

🛒 Example 1: E-commerce Product Manager

Let’s see ESLint in action with a real project:

// 🛍️ Product interface with ESLint watching
interface Product {
  id: string;
  name: string;
  price: number;
  category: 'electronics' | 'clothing' | 'books'; // 🏷️ Union type for categories
  inStock: boolean;
}

// 🏪 Product manager class
class ProductManager {
  private products: Product[] = [];
  
  // ➕ Add product method
  addProduct(product: Product): void {
    // ESLint will catch issues like:
    // - Unused variables ⚠️
    // - Missing return type annotations 📝
    // - Inconsistent naming 🎯
    
    this.products.push(product);
    console.log(`✅ Added ${product.name} to inventory!`);
  }
  
  // 🔍 Find products by category
  findByCategory(category: Product['category']): Product[] {
    return this.products.filter(product => product.category === category);
  }
  
  // 💰 Calculate total inventory value
  getTotalValue(): number {
    return this.products
      .filter(product => product.inStock)
      .reduce((total, product) => total + product.price, 0);
  }
}

// 🎮 Using our linted code
const manager = new ProductManager();
manager.addProduct({
  id: '1',
  name: 'TypeScript Handbook',
  price: 29.99,
  category: 'books',
  inStock: true
});

🎮 Example 2: Game Score System with Custom Rules

// 🎯 Custom ESLint configuration for games
// In .eslintrc.js, add custom rules:

module.exports = {
  // ... previous config
  rules: {
    // 🚫 No console.log in production
    'no-console': 'warn',
    
    // 🎯 Prefer const over let when possible
    'prefer-const': 'error',
    
    // 📝 Require explicit return types for functions
    '@typescript-eslint/explicit-function-return-type': 'warn',
    
    // 🛡️ No unused variables
    '@typescript-eslint/no-unused-vars': 'error',
    
    // ✨ Consistent naming conventions
    '@typescript-eslint/naming-convention': [
      'error',
      {
        selector: 'interface',
        format: ['PascalCase'],
        prefix: ['I'], // 🏷️ Interfaces start with 'I'
      },
      {
        selector: 'class',
        format: ['PascalCase'],
      }
    ],
  },
};

// 🎮 Game code that follows our rules
interface IGamePlayer {
  id: string;
  username: string;
  score: number;
  level: number;
}

class GameSession {
  private players: IGamePlayer[] = [];
  
  // ✅ ESLint approves: explicit return type, const usage
  public addPlayer(player: IGamePlayer): void {
    const existingPlayer = this.findPlayer(player.id);
    if (existingPlayer) {
      throw new Error(`Player ${player.username} already exists! 🚫`);
    }
    
    this.players.push(player);
    // Note: ESLint warns about console.log in production
    console.log(`🎉 Welcome ${player.username}!`);
  }
  
  // 🔍 Private helper method
  private findPlayer(id: string): IGamePlayer | undefined {
    return this.players.find(player => player.id === id);
  }
}

🚀 Advanced Configuration

🧙‍♂️ Advanced Rules and Overrides

For larger projects, you might need more sophisticated configuration:

// 🎯 Advanced .eslintrc.js
module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
    project: './tsconfig.json',
  },
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    '@typescript-eslint/recommended-requiring-type-checking', // 🚀 More strict rules
  ],
  
  // 🎨 File-specific overrides
  overrides: [
    {
      // 🧪 Relaxed rules for test files
      files: ['**/*.test.ts', '**/*.spec.ts'],
      rules: {
        '@typescript-eslint/no-explicit-any': 'off',
        'no-console': 'off',
      },
    },
    {
      // 📜 Different rules for config files
      files: ['*.config.js', '*.config.ts'],
      rules: {
        '@typescript-eslint/no-require-imports': 'off',
      },
    },
  ],
  
  // ⚙️ Custom rule configuration
  rules: {
    // 🎯 TypeScript-specific rules
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/explicit-function-return-type': 'warn',
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/prefer-nullish-coalescing': 'error',
    '@typescript-eslint/prefer-optional-chain': 'error',
    
    // 📝 General code quality
    'prefer-const': 'error',
    'no-var': 'error',
    'eqeqeq': 'error',
    'curly': 'error',
  },
};

🛠️ Integration with VS Code

Add these settings to your VS Code settings.json:

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.format.enable": true
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Parser Configuration Issues

// ❌ Wrong - ESLint doesn't understand TypeScript syntax
// Error: Parsing error: Unexpected token ':'

interface User {
  name: string;  // 💥 ESLint confused by TypeScript syntax
}

// ✅ Solution: Proper parser configuration in .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser', // 🔧 This fixes the issue!
  parserOptions: {
    project: './tsconfig.json',
  },
  // ... rest of config
};

🤯 Pitfall 2: Conflicting Rules

// ⚠️ TypeScript and ESLint might disagree
function processData(data: any): void { // ESLint warns about 'any'
  console.log(data); // ESLint warns about console.log
}

// ✅ Better approach - configure rules thoughtfully
// In .eslintrc.js:
module.exports = {
  rules: {
    // 🎯 Allow any in specific cases
    '@typescript-eslint/no-explicit-any': ['error', {
      ignoreRestArgs: true, // Allow ...args: any[]
    }],
    
    // 🔧 Allow console in development
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
  },
};

🚨 Pitfall 3: Performance Issues

// ❌ Slow configuration - lints everything
module.exports = {
  // Missing ignorePatterns - lints node_modules! 
};

// ✅ Optimized configuration
module.exports = {
  // 🚀 Ignore unnecessary files
  ignorePatterns: [
    'node_modules/',
    'dist/',
    'build/',
    '*.js.map',
  ],
  
  // 📁 Only lint TypeScript files we care about
  overrides: [
    {
      files: ['src/**/*.ts', 'src/**/*.tsx'],
      // Apply strict rules only to source files
    },
  ],
};

🛠️ Best Practices

🎯 Start Simple: Begin with recommended configurations, then customize
📝 Document Rules: Comment why you disabled or modified rules
🔄 Use CI Integration: Run ESLint in your build pipeline
⚡ Optimize Performance: Use .eslintignore for large files
👥 Team Agreement: Agree on rules before implementing
🔧 Auto-fix When Possible: Use --fix flag for automatic corrections
📊 Regular Reviews: Periodically review and update your rules

🎨 Package.json Scripts

Add these helpful scripts:

{
  "scripts": {
    "lint": "eslint src/**/*.{ts,tsx}",
    "lint:fix": "eslint src/**/*.{ts,tsx} --fix",
    "lint:check": "eslint src/**/*.{ts,tsx} --max-warnings 0"
  }
}

🧪 Hands-On Exercise

🎯 Challenge: Set Up ESLint for a TypeScript Project

Create a complete ESLint setup for a fictional social media app:

📋 Requirements:

✅ Configure ESLint for TypeScript with strict rules
🏷️ Set up naming conventions for interfaces, classes, and variables
🧪 Different rules for test files
🎨 Integration with Prettier for formatting
📝 Custom rules for your team’s coding standards
🚀 Performance optimization with ignore patterns

🚀 Bonus Points:

Add pre-commit hooks with husky
Set up VS Code integration
Create different configs for development vs production
Add custom ESLint plugin rules

💡 Solution

🔍 Click to see solution

# 📦 Install complete ESLint setup
npm install --save-dev \
  eslint \
  @typescript-eslint/parser \
  @typescript-eslint/eslint-plugin \
  prettier \
  eslint-config-prettier \
  eslint-plugin-prettier \
  husky \
  lint-staged

// 🎯 Complete .eslintrc.js configuration
module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module',
    project: './tsconfig.json',
  },
  plugins: ['@typescript-eslint', 'prettier'],
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    '@typescript-eslint/recommended-requiring-type-checking',
    'prettier', // 🎨 Prettier integration
  ],
  
  // 🚀 Performance optimization
  ignorePatterns: [
    'node_modules/',
    'dist/',
    'build/',
    'coverage/',
    '*.config.js',
  ],
  
  // 📁 File-specific configurations
  overrides: [
    {
      // 🧪 Test files
      files: ['**/*.test.ts', '**/*.spec.ts', 'src/test/**/*'],
      rules: {
        '@typescript-eslint/no-explicit-any': 'off',
        '@typescript-eslint/no-non-null-assertion': 'off',
        'no-console': 'off',
      },
    },
    {
      // 📜 Configuration files
      files: ['*.config.{js,ts}', 'scripts/**/*'],
      rules: {
        '@typescript-eslint/no-require-imports': 'off',
        'no-console': 'off',
      },
    },
  ],
  
  // ⚙️ Comprehensive rule set
  rules: {
    // 🎯 TypeScript-specific rules
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/explicit-function-return-type': 'warn',
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/prefer-nullish-coalescing': 'error',
    '@typescript-eslint/prefer-optional-chain': 'error',
    '@typescript-eslint/no-floating-promises': 'error',
    
    // 🏷️ Naming conventions
    '@typescript-eslint/naming-convention': [
      'error',
      {
        selector: 'interface',
        format: ['PascalCase'],
        prefix: ['I'],
      },
      {
        selector: 'typeAlias',
        format: ['PascalCase'],
      },
      {
        selector: 'class',
        format: ['PascalCase'],
      },
      {
        selector: 'enum',
        format: ['PascalCase'],
      },
      {
        selector: 'variable',
        format: ['camelCase', 'UPPER_CASE'],
      },
      {
        selector: 'function',
        format: ['camelCase'],
      },
    ],
    
    // 📝 Code quality rules
    'prefer-const': 'error',
    'no-var': 'error',
    'eqeqeq': 'error',
    'curly': 'error',
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    
    // 🎨 Prettier integration
    'prettier/prettier': 'error',
  },
  
  // 🌍 Environment settings
  env: {
    node: true,
    browser: true,
    es2020: true,
    jest: true,
  },
};

// 📦 package.json scripts
{
  "scripts": {
    "lint": "eslint src/**/*.{ts,tsx}",
    "lint:fix": "eslint src/**/*.{ts,tsx} --fix",
    "lint:check": "eslint src/**/*.{ts,tsx} --max-warnings 0",
    "format": "prettier --write src/**/*.{ts,tsx,json,md}",
    "type-check": "tsc --noEmit",
    "pre-commit": "lint-staged"
  },
  "lint-staged": {
    "src/**/*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  }
}

// 🎨 .prettierrc.js
module.exports = {
  semi: true,
  trailingComma: 'es5',
  singleQuote: true,
  printWidth: 80,
  tabWidth: 2,
  useTabs: false,
};

🎓 Key Takeaways

You’ve mastered ESLint with TypeScript! Here’s what you can now do:

✅ Set up ESLint for any TypeScript project with confidence 💪
✅ Configure custom rules that match your team’s standards 🛡️
✅ Integrate with your IDE for real-time feedback 🎯
✅ Debug configuration issues like a pro 🐛
✅ Optimize performance for large codebases 🚀

Remember: ESLint is your coding partner, not your enemy! It’s here to help you write amazing TypeScript code. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered ESLint with TypeScript!

Here’s what to do next:

💻 Set up ESLint in your current TypeScript project
🏗️ Experiment with different rule configurations
📚 Explore our next tutorial: “Prettier and TypeScript: Code Formatting”
🌟 Share your clean, linted code with the world!

Remember: Every TypeScript expert started with their first ESLint configuration. Keep experimenting, keep learning, and most importantly, enjoy writing beautiful, clean code! 🚀

Happy linting! 🎉🚀✨

Prerequisites

What you'll learn