@zerebos/eslint-config-typescript

A comprehensive TypeScript ESLint configuration that extends the base config with TypeScript-specific rules and best practices.

Features

• 🚀 Built on typescript-eslint recommended configurations
• 📦 Optionally extends @zerebos/eslint-config for consistency
• 🔒 Type safety enforcement and best practices
• 🎯 Performance optimizations for TypeScript projects
• 🧹 Modern TypeScript patterns (ES2022+ with TypeScript)
• ⚡ Smart type-aware linting rules
• 🔧 Flexible configuration for different TypeScript setups

Installation

npm install -D @zerebos/eslint-config-typescript eslint typescript

Usage

Basic Setup

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

import {typescript} from "@zerebos/eslint-config-typescript";

export default typescript;

With Specific Environment

Combine with environment-specific base configs:

import {node} from "@zerebos/eslint-config";
import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...node,
  ...typescript
];

Custom TypeScript Configuration

If your tsconfig.json is in a non-standard location:

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
    {
        ...typescript
        project: "./config/tsconfig.json"
    }
];

Monorepo Setup

For projects with multiple TypeScript configurations:

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
    {
        files: ["apps/api/**/*.ts"],
        project: "./apps/api/tsconfig.json",
        ...typescript
    },
    {
        files: ["apps/web/**/*.ts"],
        project: "./apps/web/tsconfig.json",
        ...typescript
    }
];

Extending the Configuration

Override or add custom rules as needed:

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...typescript,
  {
    rules: {
      // Override TypeScript rules
      "@typescript-eslint/no-unused-vars": "warn",
      "@typescript-eslint/explicit-function-return-type": "error",

      // Disable specific rules
      "@typescript-eslint/no-explicit-any": "off"
   }
 }
];

What's Included

File Targeting

• **/*.ts - TypeScript files
• **/*.tsx - TypeScript React files
• **/*.mts - TypeScript ES modules
• **/*.cts - TypeScript CommonJS modules

Base Configuration

Includes all rules from @zerebos/eslint-config plus TypeScript-specific enhancements.

Key TypeScript Rules

Type Safety & Correctness

• Strict Type Checking: Prevents any usage, enforces proper typing
• Promise Handling: Requires proper async/await and Promise handling
• Null Safety: Prevents null/undefined access errors
• Type Assertions: Controls type assertion usage

Modern TypeScript Patterns

• Interface vs Type: Consistent usage patterns
• Enum Conventions: Proper enum declaration and usage
• Generic Constraints: Proper generic type usage
• Module Boundaries: Import/export best practices

Performance & Best Practices

• Unnecessary Type Annotations: Removes redundant type information
• Prefer Optional Chaining: Modernizes null checking patterns
• Consistent Type Imports: Enforces import type for type-only imports
• Method Signatures: Consistent method declaration styles

Disabled JavaScript Rules

The following JavaScript rules are disabled in favor of their TypeScript equivalents:

• no-unused-vars → @typescript-eslint/no-unused-vars
• no-redeclare → @typescript-eslint/no-redeclare
• no-use-before-define → @typescript-eslint/no-use-before-define
• no-shadow → @typescript-eslint/no-shadow

Configuration Details

Parser Configuration

• Parser: @typescript-eslint/parser
• Parser Options: Project service enabled for type-aware rules
• ECMAScript Version: Latest (ES2022+)
• Source Type: Module

Type-Aware Rules

This configuration enables type-aware linting, which provides more accurate analysis but requires a tsconfig.json file. Make sure you have:

1. A valid tsconfig.json in your project root
2. TypeScript installed as a dependency
3. All TypeScript files included in your TypeScript project

Recommended TypeScript Compiler Options

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true
 }
}

Integration with Other Tools

Prettier

This config works seamlessly with Prettier. Install the TypeScript parser:

npm install -D prettier @prettier/plugin-typescript

VS Code

For the best TypeScript experience:

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
 }
}

Jest/Vitest

For testing files, you might want to relax some rules:

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...typescript,
  {
    files: ["**/*.test.ts", "**/*.spec.ts"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-non-null-assertion": "off"
   }
 }
];

Common Use Cases

Node.js API with TypeScript

import {node} from "@zerebos/eslint-config";
import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...node,
  ...typescript
];

React TypeScript Project

import {browser} from "@zerebos/eslint-config";
import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...browser,
  ...typescript
];

TypeScript Library

import {universal} from "@zerebos/eslint-config";
import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...universal,
  ...typescript,
  {
    rules: {
      // Libraries should have explicit return types
      "@typescript-eslint/explicit-function-return-type": "error",
      "@typescript-eslint/explicit-module-boundary-types": "error"
   }
 }
];

Monorepo with Mixed JavaScript/TypeScript

import {universal} from "@zerebos/eslint-config";
import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  // JavaScript files get base config
  ...universal,

  // TypeScript files get additional rules
  {
    files: ["**/*.ts", "**/*.tsx"],
    ...typescript
 }
];

Migration Guide

From JavaScript to TypeScript

1. Install this config alongside your existing base config
2. Add TypeScript file patterns to your ESLint configuration
3. Gradually migrate files from .js to .ts
4. Address TypeScript-specific linting errors

From @typescript-eslint/eslint-plugin

Replace your manual TypeScript ESLint setup:

Before:

import tseslint from "typescript-eslint";

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

After:

import {typescript} from "@zerebos/eslint-config-typescript";

export default typescript;

Troubleshooting

"Parsing error: Cannot read file"

Ensure your tsconfig.json includes all files you want to lint:

{
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["node_modules", "dist"]
}

Performance Issues

For large projects, consider:

1. Using parserOptions.projectService: true instead of explicit project paths
2. Excluding unnecessary files in your tsconfig.json
3. Using ESLint's --cache flag

Type-aware rules not working

Verify that:

1. Your tsconfig.json is valid and includes the files being linted
2. TypeScript is installed and accessible
3. The parser can find your TypeScript configuration

Rule Customization Examples

Strict Library Configuration

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...typescript,
  {
    rules: {
      "@typescript-eslint/no-explicit-any": "error",
      "@typescript-eslint/explicit-function-return-type": "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"
   }
 }
];

Relaxed Application Configuration

import {typescript} from "@zerebos/eslint-config-typescript";

export default [
  ...typescript,
  {
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/explicit-function-return-type": "off",
      "@typescript-eslint/no-unused-vars": ["warn", {"argsIgnorePattern": "^_"}]
   }
 }
];

Contributing

Issues and pull requests are welcome! Please check the main repository for contribution guidelines.

Related Packages

• @zerebos/eslint-config - Base ESLint configuration
• @zerebos/eslint-config-svelte - Svelte with TypeScript ESLint configuration