@stackvault/eslint-config-typescript

Modern TypeScript ESLint configuration with strict type checking and comprehensive stylistic rules. Built for ESLint 9+ flat config with full TypeScript 5.5+ support.

Features

• ✨ ESLint 9 Flat Config - Modern configuration format with better performance
• 🎯 Strict Type Checking - Comprehensive type-aware rules to catch errors at build time
• 🎨 Built-in Formatting - Replaces Prettier with @stylistic/eslint-plugin for unified tooling
• 🚀 TypeScript 5.5+ Support - Leverages latest TypeScript features and optimizations
• 📦 Zero Config Philosophy - Sensible defaults that work out of the box
• ⚡ Performance Optimized - Uses projectService for faster type checking

Installation

npm install --save-dev @stackvault/eslint-config-typescript eslint typescript

or with Yarn:

yarn add --dev @stackvault/eslint-config-typescript eslint typescript

Requirements

• Node.js >=18.18.0
• ESLint >=9.22.0
• TypeScript >=5.5.0

Usage

Create an eslint.config.js file in your project root:

import typeScriptConfig from '@stackvault/eslint-config-typescript';

export default [
  ...typeScriptConfig,
  // Your custom rules here
];

With Custom Rules

import typeScriptConfig from '@stackvault/eslint-config-typescript';

export default [
  ...typeScriptConfig,
  {
    rules: {
      // Override or add custom rules
      'no-console': 'off',
      '@typescript-eslint/no-explicit-any': 'warn',
    }
  }
];

For Monorepos

import typeScriptConfig from '@stackvault/eslint-config-typescript';

export default [
  ...typeScriptConfig,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
        project: ['./packages/*/tsconfig.json'],
      }
    }
  }
];

What's Included

Type Safety Rules

• Strict type checking with strictTypeChecked and stylisticTypeChecked configs
• No unsafe operations - Prevents any type pollution
• Smart boolean expressions - Allows practical nullish checks while maintaining safety
• Comprehensive async/promise rules - Ensures proper handling of asynchronous code

Code Organization

• Enforced import sorting with eslint-plugin-simple-import-sort
• Consistent type imports - Prefers import { type User } syntax
• Naming conventions - PascalCase for types/interfaces, T-prefix for generics
• Explicit return types for functions (with smart exceptions)

Stylistic Rules (Prettier Replacement)

Built-in formatting rules via @stylistic/eslint-plugin:

• 2-space indentation
• Single quotes
• Semicolons required
• Trailing commas in multiline
• 120 character line limit
• Consistent spacing and formatting

Special File Handling

• Test files (*.spec.ts, *.test.ts) - Relaxed rules for testing
• JavaScript files - Type checking disabled, basic linting enabled
• Declaration files (*.d.ts) - Minimal rules for type definitions

Key Rules Explained

Type Safety

// ❌ Error: no-explicit-any
const data: any = fetchData();

// ✅ Correct
const data: User = fetchData();

Smart Boolean Expressions

// ✅ Allowed - practical nullish checks
if (user) { }  // User | null
if (isEnabled) { }  // boolean | undefined

// ❌ Error - string/number coercion
if (userName) { }  // string (use userName !== '')
if (count) { }  // number (use count !== 0)

Async/Promise Handling

// ❌ Error: no-floating-promises
fetchData();

// ✅ Correct
await fetchData();
// or
void fetchData();

Import Organization

// ✅ Automatically sorted and organized
import { type User, type Product } from '@/types';
import { calculateTotal } from '@/utils';
import React from 'react';

VSCode Integration

Add to .vscode/settings.json:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.experimental.useFlatConfig": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

Package.json Scripts

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "lint:debug": "eslint . --debug",
    "type-check": "tsc --noEmit"
  }
}

Migration from ESLint 8

1. Remove .eslintrc.* files
2. Create eslint.config.js with flat config
3. Update VSCode settings for flat config
4. Remove Prettier (this config handles formatting)

Performance Tips

• Use projectService: true for better TypeScript performance
• Enable ESLint cache: eslint . --cache
• Exclude build directories in your tsconfig.json
• Consider using --max-warnings 0 in CI/CD

Philosophy

This configuration prioritizes:

1. Type Safety - Catch errors at build time, not runtime
2. Consistency - Unified formatting without Prettier
3. Performance - Optimized for large TypeScript projects
4. Developer Experience - Clear errors with practical rules

License

MIT

Contributing

Issues and PRs welcome at GitHub