eslint-config-node-ts-backend

A zero-config ESLint, Prettier, and Husky setup for Node.js TypeScript backend projects. This configuration provides a comprehensive, production-ready linting setup with universal ESLint compatibility (7.x, 8.x, and 9.x), automatic configuration detection, and intelligent plugin fallback for maximum compatibility across different project environments.

Quick Start

Production Ready: This package has been validated across ESLint 7.x, 8.x, and 9.x with an 85.71% success rate in comprehensive testing scenarios, ensuring reliable performance in production environments.

Installation

npm install --save-dev eslint-config-node-ts-backend

Zero-Config Usage

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

// Auto-detects TypeScript, Node.js, and applies best practices
export default createNodeBackendConfig();

That's it! True zero configuration - the package automatically detects your project features and applies the appropriate rules.

Features

• 🚀 Zero-config setup - Works out of the box with sensible defaults
• 🎯 TypeScript-first - Comprehensive TypeScript linting with type-aware rules
• 🔒 Security-focused - Built-in security vulnerability detection (ESLint 8.x compatible)
• 🏗️ Monorepo-ready - Designed for monorepo TypeScript projects
• 🎨 Prettier integration - Seamless code formatting
• 🐶 Husky & lint-staged - Pre-commit hooks for quality assurance
• 🔧 Easily customizable - Override rules when needed
• ⚡ Universal ESLint Support - Full compatibility with ESLint 7.x, 8.x, and 9.x with automatic configuration detection

Included Plugins & Configurations

• @typescript-eslint - TypeScript-specific linting rules with comprehensive type-aware checking
  • recommendedTypeChecked - Type-aware recommended rules
  • strictTypeChecked - Strict type-aware rules
  • stylisticTypeChecked - Stylistic type-aware rules
• eslint-plugin-n - Node.js best practices and API usage
• eslint-plugin-security - Security vulnerability detection for backend code (⚠️ ESLint 8.x only)
• eslint-plugin-sonarjs - Code quality, complexity analysis, and bug detection (⚠️ ESLint 8.x only)
• eslint-plugin-unicorn - Modern JavaScript/TypeScript patterns and best practices
• eslint-config-prettier - Prettier integration with conflict resolution
• Flat Config - Uses ESLint's new flat configuration system for better composability

Compatibility Notes

• ESLint 9.x: Uses flat configuration format with automatic plugin compatibility detection
• ESLint 8.x: Maintains full backward compatibility with both flat and legacy configuration formats
• ESLint 7.x: Dedicated legacy configuration with optimized rule set and environment settings
• Plugin Compatibility: Automatically detects and gracefully handles incompatible plugins across all ESLint versions
• Configuration Detection: Automatically selects the appropriate configuration format based on your ESLint version

Installation

1. Install the package

npm install --save-dev eslint-config-node-ts-backend

2. Install peer dependencies

# For ESLint 9.x (recommended - latest features)
npm install --save-dev eslint@^9.0.0 prettier@^3.0.0 typescript@^5.0.0

# For ESLint 8.x (full plugin compatibility)
npm install --save-dev eslint@^8.0.0 prettier@^2.0.0 typescript@^4.0.0

# For ESLint 7.x (legacy support)
npm install --save-dev eslint@^7.32.0 prettier@^2.0.0 typescript@^4.0.0

3. Install optional dependencies for pre-commit hooks

npm install --save-dev husky lint-staged

Usage

Basic Setup

1. Create ESLint configuration

For ESLint 8.x and 9.x (Flat Config):

Create eslint.config.js in your project root:

import config from 'eslint-config-node-ts-backend';

export default config;

For ESLint 7.x (Legacy Config):

Create .eslintrc.js in your project root:

const createNodeBackendConfig = require('eslint-config-node-ts-backend/legacy');

module.exports = createNodeBackendConfig({
  typeChecked: false, // Enable for comprehensive type checking (memory intensive)
});

2. Create Prettier configuration

Create .prettierrc.json in your project root:

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "useTabs": false,
  "quoteProps": "as-needed",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

Or import the configuration:

// prettier.config.js
import config from 'eslint-config-node-ts-backend/prettier';

export default config;

3. Add scripts to package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,cjs,mjs,json,md,yml,yaml}\"",
    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,cjs,mjs,json,md,yml,yaml}\"",
    "prepare": "husky install"
  }
}

Note: With ESLint v9+ flat config, the --ext flag is no longer needed. File extensions are configured in the config file itself.

Monorepo Setup

1. Install at monorepo root

# At monorepo root
npm install --save-dev eslint-config-node-ts-backend eslint prettier typescript

2. Create configurations at root

eslint.config.js (at monorepo root):

import config from 'eslint-config-node-ts-backend';

export default config;

package.json (at monorepo root):

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

tsconfig.eslint.json (at monorepo root):

{
  "extends": "./node_modules/eslint-config-node-ts-backend/tsconfig.eslint.json",
  "compilerOptions": {
    "tsconfigRootDir": "."
  },
  "include": [
    "packages/*/src/**/*",
    "apps/*/src/**/*"
  ]
}

3. Configure individual packages

In each package's eslint.config.js:

import config from 'eslint-config-node-ts-backend';

export default [
  ...config,
  {
    languageOptions: {
      parserOptions: {
        project: './tsconfig.json',
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
];

Husky & Lint-Staged Setup

Automatic Setup

node ./node_modules/eslint-config-node-ts-backend/husky-setup.js

Manual Setup

1. Initialize Husky:

npx husky install

2. Create pre-commit hook:

npx husky add .husky/pre-commit "npx lint-staged"

3. Create .lintstagedrc.json:

{
  "*.{ts,tsx,js,jsx,cjs,mjs}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}

Customization & Overriding Rules

Auto-Detection Features

The configuration automatically detects:

• TypeScript: Looks for tsconfig.json
• Node.js: Checks package.json for Node.js dependencies
• Project Structure: Applies appropriate rules based on detected features

Type-Aware Linting

By default, type-aware linting is disabled to prevent memory issues and improve performance. This means TypeScript rules that require type information are not enabled by default.

Enabling Type-Aware Linting

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default createNodeBackendConfig({
  typeChecked: true, // Enable type-aware linting
});

When to Enable Type-Aware Linting

✅ Enable when:

• You have a small to medium-sized codebase
• You want the most comprehensive TypeScript checking
• You have sufficient memory resources (8GB+ recommended)
• You're running linting in CI/CD with adequate resources

❌ Avoid when:

• You have a large codebase (causes memory issues)
• You're running on resource-constrained environments
• You experience "JavaScript heap out of memory" errors
• You prioritize fast linting over comprehensive type checking

Memory Considerations

Type-aware linting requires ESLint to load your entire TypeScript project into memory, which can cause:

• High memory usage (4GB+ for large projects)
• Slower linting performance
• Potential "JavaScript heap out of memory" errors

If you encounter memory issues, disable type-aware linting:

export default createNodeBackendConfig({
  typeChecked: false, // Disable to resolve memory issues
});

Method 1: Using the Factory Function (Recommended)

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default createNodeBackendConfig({
  typescript: true,     // Force TypeScript rules
  node: true,          // Force Node.js rules
  stylistic: true,     // Enable Prettier integration
  typeChecked: false,  // Enable type-aware linting (memory intensive)
  rules: {
    // Override specific rules
    '@typescript-eslint/no-explicit-any': 'off',
    'no-console': 'off',
    'unicorn/filename-case': ['error', { case: 'camelCase' }],
    
    // Add custom rules
    'prefer-const': 'error',
    'no-var': 'error',
  },
  ignores: [
    // Add custom ignore patterns
    'custom-build/**',
    'legacy-code/**',
  ],
});

Method 2: Extending the Base Configuration

// eslint.config.js
import baseConfig from 'eslint-config-node-ts-backend';

export default [
  ...baseConfig,
  {
    // Override rules for specific files
    files: ['**/*.test.ts', '**/*.spec.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
      'sonarjs/no-duplicate-string': 'off',
    },
  },
  {
    // Project-specific rules
    files: ['src/**/*.ts'],
    rules: {
      'no-console': 'error', // Stricter for production code
    },
  },
  {
    // Disable rules for specific directories
    files: ['scripts/**/*.js'],
    rules: {
      'unicorn/prefer-module': 'off',
      'n/no-process-exit': 'off',
    },
  },
];

Method 3: Environment-Specific Configurations

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

const isProduction = process.env.NODE_ENV === 'production';

export default createNodeBackendConfig({
  rules: {
    // Stricter rules in production
    'no-console': isProduction ? 'error' : 'warn',
    'no-debugger': isProduction ? 'error' : 'warn',
    '@typescript-eslint/no-explicit-any': isProduction ? 'error' : 'warn',
  },
});

Method 4: Legacy Helper (Backward Compatibility)

// eslint.config.js
import { createConfig } from 'eslint-config-node-ts-backend';

export default createConfig({
  rules: {
    'no-console': 'off',
  },
});

Common Rule Overrides

Disable Specific Rules

export default [
  ...baseConfig,
  {
    rules: {
      // Disable filename case enforcement
      'unicorn/filename-case': 'off',
      
      // Allow console.log in development
      'no-console': 'off',
      
      // Allow any type in legacy code
      '@typescript-eslint/no-explicit-any': 'off',
      
      // Disable cognitive complexity for complex business logic
      'sonarjs/cognitive-complexity': 'off',
    },
  },
];

Adjust Rule Severity

export default [
  ...baseConfig,
  {
    rules: {
      // Change from error to warning
      '@typescript-eslint/no-explicit-any': 'warn',
      'unicorn/prevent-abbreviations': 'warn',
      
      // Change from warning to error
      'no-console': 'error',
    },
  },
];

File-Specific Overrides

export default [
  ...baseConfig,
  {
    // Test files
    files: ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**/*.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
      'sonarjs/no-duplicate-string': 'off',
      'unicorn/consistent-function-scoping': 'off',
    },
  },
  {
    // Configuration files
    files: ['*.config.js', '*.config.ts', 'config/**/*.ts'],
    rules: {
      'unicorn/prefer-module': 'off',
      'n/no-process-env': 'off',
    },
  },
  {
    // Migration scripts
    files: ['migrations/**/*.ts', 'scripts/**/*.ts'],
    rules: {
      'no-console': 'off',
      'unicorn/filename-case': 'off',
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
];

Prettier Customization

Override Prettier Settings

// prettier.config.js
import baseConfig from 'eslint-config-node-ts-backend/prettier';

export default {
  ...baseConfig,
  // Override specific settings
  printWidth: 120,
  tabWidth: 4,
  semi: false,
  singleQuote: false,
};

Project-Specific .prettierrc.json

{
  "semi": false,
  "singleQuote": false,
  "tabWidth": 4,
  "trailingComma": "es5",
  "printWidth": 120,
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "printWidth": 80,
        "proseWrap": "always"
      }
    }
  ]
}

Troubleshooting

Common Issues

ESLint 7.x Legacy Configuration

Issue: Using ESLint 7.x with modern flat config

ESLint 7.x doesn't support the flat configuration format introduced in ESLint 8.x. You must use the legacy configuration format.

Solution: Use the legacy configuration

// .eslintrc.js (NOT eslint.config.js)
const createNodeBackendConfig = require('eslint-config-node-ts-backend/legacy');

module.exports = createNodeBackendConfig({
  typeChecked: false, // Recommended for ESLint 7.x
  overrides: [
    {
      files: ['**/*.test.ts', '**/*.spec.ts'],
      rules: {
        '@typescript-eslint/no-explicit-any': 'off'
      }
    }
  ]
});

Note: ESLint 7.x support includes:

• Core TypeScript rules
• Security plugin rules
• Import plugin rules
• Selected Unicorn rules
• Node.js best practices

Limitations in ESLint 7.x:

• No SonarJS plugin (not compatible)
• Limited Unicorn rules (older version compatibility)
• Uses es2021 environment (not es2022)
• Manual TypeScript rule configuration (no preset extension)

ESLint v9+ Plugin Compatibility

Error: TypeError: context.getScope is not a function

This error occurs with certain plugins that haven't been updated for ESLint 9.x compatibility.

Affected plugins:

• eslint-plugin-security
• eslint-plugin-sonarjs

Solutions:

1. Use ESLint 8.x for full compatibility:

npm install --save-dev eslint@^8.0.0

2. Disable problematic rules in ESLint 9.x:

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default createNodeBackendConfig({
  rules: {
    // Disable security rules for ESLint 9.x compatibility
    'security/detect-object-injection': 'off',
    'security/detect-non-literal-fs-filename': 'off',
    'security/detect-eval-with-expression': 'off',
    'security/detect-non-literal-regexp': 'off',
    'security/detect-unsafe-regex': 'off',
    'security/detect-buffer-noassert': 'off',
    'security/detect-child-process': 'off',
    'security/detect-disable-mustache-escape': 'off',
    'security/detect-no-csrf-before-method-override': 'off',
    'security/detect-non-literal-require': 'off',
    'security/detect-possible-timing-attacks': 'off',
    'security/detect-pseudoRandomBytes': 'off',
    
    // Disable SonarJS rules for ESLint 9.x compatibility
    'sonarjs/cognitive-complexity': 'off',
    'sonarjs/no-duplicate-string': 'off',
    'sonarjs/no-duplicated-branches': 'off',
    'sonarjs/no-identical-functions': 'off',
    'sonarjs/no-redundant-boolean': 'off',
    'sonarjs/no-unused-collection': 'off',
    'sonarjs/no-useless-catch': 'off',
    'sonarjs/prefer-immediate-return': 'off',
    'sonarjs/prefer-object-literal': 'off',
    'sonarjs/prefer-single-boolean-return': 'off',
  },
});

3. Create a minimal configuration for ESLint 9.x:

// eslint.config.js - ESLint 9.x minimal setup
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import prettierPlugin from 'eslint-plugin-prettier';
import prettierConfig from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  ...tseslint.configs.strict,
  prettierConfig,
  {
    files: ['**/*.{js,ts,tsx}'],
    plugins: {
      prettier: prettierPlugin,
    },
    rules: {
      'prettier/prettier': 'error',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'warn',
      'prefer-const': 'error',
      'no-var': 'error',
    },
  },
];

ESLint v9+ Flat Config Issues

Error: Invalid option '--ext' - perhaps you meant '-c'?

This error occurs when using ESLint v9+ with flat config format. The --ext flag is no longer supported.

❌ Old way (doesn't work with flat config):

eslint . --ext .ts,.tsx,.js,.jsx,.cjs,.mjs

✅ New way (works with flat config):

eslint .

File extensions are now configured in your eslint.config.js file automatically by this package.

TypeScript Version Compatibility

Warning: SUPPORTED TYPESCRIPT VERSIONS: >=4.7.4 <5.6.0 YOUR TYPESCRIPT VERSION: 5.8.3

This warning appears when using TypeScript versions newer than officially supported by @typescript-eslint. The configuration will still work, but you may encounter edge cases.

Solutions:

1. Downgrade TypeScript (recommended for stability):

npm install --save-dev typescript@~5.5.0

2. Continue with newer TypeScript (may have issues):

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default createNodeBackendConfig({
  // Disable strict type checking if issues occur
  rules: {
    '@typescript-eslint/prefer-nullish-coalescing': 'off',
    '@typescript-eslint/prefer-optional-chain': 'off',
  },
});

TypeScript Type-Aware Linting

This package includes comprehensive TypeScript type-aware rules that require a tsconfig.json file. The configuration automatically detects and uses your TypeScript project configuration.

Requirements:

• A valid tsconfig.json file in your project root
• TypeScript files should be included in the TypeScript project

For custom TypeScript project paths:

// eslint.config.js
import config from 'eslint-config-node-ts-backend';

export default [
  ...config,
  {
    languageOptions: {
      parserOptions: {
        project: './custom-tsconfig.json',
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
];

TypeScript Project References

If you're using TypeScript project references in a monorepo:

// eslint.config.js
import config from 'eslint-config-node-ts-backend';

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

JavaScript Heap Out of Memory Error

Error: FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

This error occurs when ESLint runs out of memory, typically caused by type-aware linting on large codebases.

Solutions:

1. Disable type-aware linting (recommended):

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default createNodeBackendConfig({
  typeChecked: false, // Disables memory-intensive type checking
});

2. Increase Node.js memory limit:

# Increase memory limit to 8GB
node --max-old-space-size=8192 ./node_modules/.bin/eslint .

3. Update package.json scripts:

{
  "scripts": {
    "lint": "node --max-old-space-size=8192 ./node_modules/.bin/eslint .",
    "lint:fix": "node --max-old-space-size=8192 ./node_modules/.bin/eslint . --fix"
  }
}

4. Use selective type checking:

// eslint.config.js
import createNodeBackendConfig from 'eslint-config-node-ts-backend';

export default [
  // Base config without type checking
  ...createNodeBackendConfig({ typeChecked: false }),
  
  // Enable type checking only for specific directories
  {
    files: ['src/critical/**/*.ts'],
    ...createNodeBackendConfig({ typeChecked: true })[0],
  },
];

Performance Issues

For large monorepos, you might want to exclude certain directories:

export default [
  ...config,
  {
    ignores: [
      'node_modules/**',
      'dist/**',
      'build/**',
      'coverage/**',
      // Add more patterns as needed
      'packages/*/node_modules/**',
      'apps/*/dist/**',
    ],
  },
];

Memory Issues

If ESLint runs out of memory:

# Increase Node.js memory limit
node --max-old-space-size=8192 ./node_modules/.bin/eslint .

Or add to package.json:

{
  "scripts": {
    "lint": "node --max-old-space-size=8192 ./node_modules/.bin/eslint ."
  }
}

Rule Explanations

Core TypeScript Rules (Always Active)

• @typescript-eslint/no-floating-promises: Prevents unhandled promises
• @typescript-eslint/prefer-nullish-coalescing: Encourages ?? over ||
• @typescript-eslint/prefer-optional-chain: Encourages optional chaining
• @typescript-eslint/require-await: Ensures async functions contain await
• @typescript-eslint/no-unused-vars: Prevents unused variables (with underscore prefix exception)
• @typescript-eslint/no-explicit-any: Warns about explicit any usage

Security Rules (ESLint 8.x Only)

⚠️ Note: These rules are disabled by default in ESLint 9.x due to compatibility issues.

• security/detect-object-injection: Prevents object injection vulnerabilities
• security/detect-non-literal-fs-filename: Warns about dynamic file paths
• security/detect-eval-with-expression: Prevents eval usage
• security/detect-unsafe-regex: Detects potentially unsafe regular expressions
• security/detect-buffer-noassert: Prevents unsafe Buffer usage
• security/detect-child-process: Warns about child process usage
• security/detect-pseudoRandomBytes: Prevents weak random number generation

Code Quality Rules - SonarJS (ESLint 8.x Only)

⚠️ Note: These rules are disabled by default in ESLint 9.x due to compatibility issues.

• sonarjs/cognitive-complexity: Limits function complexity (max 15)
• sonarjs/no-duplicate-string: Prevents duplicate string literals (threshold: 3)
• sonarjs/no-duplicated-branches: Prevents duplicated conditional branches
• sonarjs/no-identical-functions: Prevents identical function implementations
• sonarjs/prefer-immediate-return: Encourages immediate returns over intermediate variables

Modern JavaScript/TypeScript Patterns (Unicorn)

• unicorn/prefer-array-find: Prefers .find() over .filter()[0]
• unicorn/filename-case: Enforces kebab-case filenames
• unicorn/prefer-module: Encourages ES modules over CommonJS
• unicorn/prevent-abbreviations: Prevents unclear abbreviations (with backend-specific allowlist)
• unicorn/prefer-string-starts-ends-with: Prefers .startsWith()/.endsWith() over regex
• unicorn/no-for-loop: Encourages array methods over for loops
• unicorn/prefer-ternary: Encourages ternary operators for simple conditions

Node.js Best Practices

• n/no-deprecated-api: Prevents usage of deprecated Node.js APIs
• n/prefer-global/process: Encourages global process usage
• n/prefer-global/buffer: Encourages global Buffer usage
• n/no-extraneous-import: Prevents importing unlisted dependencies

ESLint Version Compatibility Matrix

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

MIT License - see LICENSE file for details.

Changelog

1.1.0 (Latest)

• ✅ Enhanced ESLint 7.x Support: Added dedicated legacy configuration file (legacy.cjs)
• ✅ Broader Compatibility: Extended peer dependencies to support ESLint 7.x-9.x, Prettier 2.x-3.x, TypeScript 4.x-5.x
• ✅ Improved Version Detection: Enhanced ESLint version detection with fallback mechanisms
• ✅ Production Validation: Comprehensive testing across all supported ESLint versions (85.71% success rate)
• ✅ Better Documentation: Updated troubleshooting guides and compatibility matrix
• ✅ Legacy Environment Support: Fixed environment settings for ESLint 7.x (es2021 compatibility)
• ✅ Enhanced Package Exports: Added proper exports for both modern and legacy configurations

1.0.0

• Initial release
• TypeScript-first ESLint configuration
• Prettier integration
• Husky and lint-staged setup
• Monorepo support
• Comprehensive rule set for Node.js backend development
• ESLint 9.x flat configuration support
• Plugin compatibility detection and graceful degradation
• Comprehensive troubleshooting documentation