ESLint con TypeScript

Qué es typescript-eslint

typescript-eslint es el proyecto que permite a ESLint analizar código TypeScript. Proporciona un parser que entiende la sintaxis de TypeScript y un conjunto de reglas específicas para detectar errores, malas prácticas y patrones problematicos en código TypeScript.

ESLint por si solo no puede analizar TypeScript porque su parser predeterminado solo entiende JavaScript estándar. typescript-eslint aporta:

• Un parser (@typescript-eslint/parser) que convierte código TypeScript en un AST compatible con ESLint
• Un plugin (@typescript-eslint/eslint-plugin) con reglas específicas para TypeScript
• Soporte para type-aware linting: reglas que consultan al compilador de TypeScript para validaciones más profundas

npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

typescript-eslint unifica parser y plugin en un solo paquete typescript-eslint desde versiones recientes, simplificando la instalación y configuración.

Flat config: configuración moderna

ESLint utiliza el formato flat config (eslint.config.mjs) como sistema de configuración predeterminado. Este formato reemplaza al antiguo .eslintrc.* y es más explícito y composable.

npm install -D eslint typescript-eslint

// archivo: eslint.config.mjs
import eslint from "@eslint/js"
import tseslint from "typescript-eslint"

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended
)

Esta configuración mínima activa las reglas recomendadas de ESLint y las reglas recomendadas de typescript-eslint.

Configuración detallada

// archivo: eslint.config.mjs
import eslint from "@eslint/js"
import tseslint from "typescript-eslint"

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["**/*.ts"],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      "@typescript-eslint/no-explicit-any": "error",
      "@typescript-eslint/no-unused-vars": ["error", {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_"
      }],
      "@typescript-eslint/explicit-function-return-type": "warn",
      "@typescript-eslint/no-inferrable-types": "off"
    }
  },
  {
    ignores: ["dist/", "node_modules/", "*.js"]
  }
)

Ejecutar ESLint

# Analizar todos los archivos TypeScript
npx eslint .

# Analizar archivos específicos
npx eslint src/

# Corregir automáticamente lo que sea posible
npx eslint . --fix

# Formato de salida detallado
npx eslint . --format stylish

Reglas fundamentales para TypeScript

typescript-eslint ofrece decenas de reglas específicas. Las más relevantes para mantener código TypeScript de calidad son:

no-explicit-any

Prohibe el uso de any explícito, forzando tipos concretos:

// Incorrecto
function procesar(datos: any): any {
  return datos.nombre
}

// Correcto
interface Entidad {
  nombre: string
}

function procesar(datos: Entidad): string {
  return datos.nombre
}

no-unused-vars

Detecta variables declaradas que no se utilizan:

// Incorrecto: variable sin usar
const temporal = 42

// Correcto: prefijo _ para parámetros ignorados intencionalmente
function manejar(_evento: Event, datos: string): void {
  console.log(datos)
}

explicit-function-return-type

Requiere declarar el tipo de retorno en las funciones:

// Aviso: falta tipo de retorno
function calcular(a: number, b: number) {
  return a + b
}

// Correcto
function calcular(a: number, b: number): number {
  return a + b
}

prefer-nullish-coalescing y prefer-optional-chaining

Fomentan el uso de operadores modernos de TypeScript:

// Antes
const nombre = usuario !== null && usuario !== undefined ? usuario.nombre : "Anonimo"

// Con optional chaining y nullish coalescing
const nombre = usuario?.nombre ?? "Anonimo"

consistent-type-imports

Fuerza el uso de import type cuando solo se importan tipos:

// Incorrecto
import { Usuario } from "./tipos"

function mostrar(u: Usuario): void {
  console.log(u.nombre)
}

// Correcto
import type { Usuario } from "./tipos"

function mostrar(u: Usuario): void {
  console.log(u.nombre)
}

Type-aware linting

Las reglas type-aware consultan al compilador de TypeScript para realizar análisis más profundos. Requieren configurar parserOptions.project para que ESLint acceda a la información de tipos:

// archivo: eslint.config.mjs
import eslint from "@eslint/js"
import tseslint from "typescript-eslint"

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  }
)

Las reglas type-aware son más lentas que las reglas regulares porque necesitan compilar el proyecto. En proyectos grandes, el análisis puede tardar significativamente más. Se recomienda usarlas en CI y como check de pre-commit.

no-floating-promises

Detecta promesas que no se manejan (sin await, .then() o .catch()):

// Incorrecto: promesa no manejada
async function obtenerDatos(): Promise<string> {
  return "datos"
}

function ejecutar(): void {
  obtenerDatos() // Advertencia: promesa flotante
}

// Correcto
async function ejecutar(): Promise<void> {
  const datos = await obtenerDatos()
  console.log(datos)
}

// También correcto: void explícito
function ejecutarSinEspera(): void {
  void obtenerDatos()
}

no-misused-promises

Detecta usos incorrectos de promesas en contextos que no las esperan:

// Incorrecto: función async en posición de callback sincrono
const números = [1, 2, 3]

// forEach no maneja promesas
números.forEach(async (n) => {
  await procesarAsync(n)
})

// Correcto: usar for...of con await
async function procesarTodos(nums: number[]): Promise<void> {
  for (const n of nums) {
    await procesarAsync(n)
  }
}

async function procesarAsync(n: number): Promise<void> {
  console.log(`Procesando: ${n}`)
}

strict-boolean-expressions

Previene el uso de valores no booleanos en contextos de condición:

// Problematico: 0 y "" son falsy pero podrían ser valores válidos
function mostrarResultado(valor: number | undefined): void {
  if (valor) { // 0 se evalua como false
    console.log(`Resultado: ${valor}`)
  }
}

// Correcto: comparación explícita
function mostrarResultado(valor: number | undefined): void {
  if (valor !== undefined) {
    console.log(`Resultado: ${valor}`)
  }
}

no-unsafe-assignment y no-unsafe-return

Detectan asignaciones y retornos de valores tipados como any:

// Incorrecto
function obtenerDatos(): any {
  return JSON.parse('{"nombre": "Ana"}')
}

const datos = obtenerDatos() // datos es any

// Correcto
interface Persona {
  nombre: string
}

function obtenerDatos(): Persona {
  const parseado: unknown = JSON.parse('{"nombre": "Ana"}')
  if (
    typeof parseado === "object" &&
    parseado !== null &&
    "nombre" in parseado &&
    typeof (parseado as Persona).nombre === "string"
  ) {
    return parseado as Persona
  }
  throw new Error("Formato inválido")
}

Configuración estricta

typescript-eslint ofrece preset strict y strictTypeChecked para proyectos que buscan máxima seguridad:

// archivo: eslint.config.mjs
import eslint from "@eslint/js"
import tseslint from "typescript-eslint"

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      // Ajustes sobre la configuración estricta
      "@typescript-eslint/no-unused-vars": ["error", {
        argsIgnorePattern: "^_",
        destructuredArrayIgnorePattern: "^_"
      }],
      "@typescript-eslint/restrict-template-expressions": ["error", {
        allowNumber: true,
        allowBoolean: true
      }]
    }
  },
  {
    ignores: ["dist/", "node_modules/"]
  }
)

Los presets disponibles, de menos a más estricto:

• recommended: reglas esenciales que previenen errores comunes
• strict: añade reglas de buenas prácticas y convenciones
• recommendedTypeChecked: recommended + reglas type-aware
• strictTypeChecked: strict + type-aware (máximo rigor)
• stylistic / stylisticTypeChecked: reglas de estilo y consistencia

Integración con Prettier

Prettier se encarga del formateo del código (indentación, longitud de linea, comillas) mientras ESLint se centra en la calidad y corrección. Para evitar conflictos entre ambos:

npm install -D prettier eslint-config-prettier

// archivo: eslint.config.mjs
import eslint from "@eslint/js"
import tseslint from "typescript-eslint"
import prettierConfig from "eslint-config-prettier"

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  prettierConfig,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  }
)

eslint-config-prettier desactiva todas las reglas de ESLint que podrían entrar en conflicto con el formateo de Prettier. Se añade al final de la lista de configuraciones para que tenga prioridad.

Configuración de Prettier:

{
  "semi": false,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "none",
  "printWidth": 100
}

Scripts de package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write \"src/**/*.ts\"",
    "format:check": "prettier --check \"src/**/*.ts\"",
    "typecheck": "tsc --noEmit",
    "check": "npm run typecheck && npm run lint && npm run format:check"
  }
}

La combinación de tsc --noEmit para verificación de tipos, ESLint para calidad de código y Prettier para formateo proporciona una cadena completa de validación. El script check ejecuta las tres herramientas y es ideal para CI/CD.

Integración con editores

Los editores modernos ejecutan ESLint automáticamente al abrir archivos TypeScript. En WebStorm e IntelliJ IDEA Ultimate la integración con ESLint viene activada por defecto y detecta la configuración eslint.config.mjs en la raíz del proyecto. Para activarla o ajustarla:

Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint

• Selecciona Automatic ESLint configuration (autodetección).
• Marca Run eslint --fix on save para aplicar correcciones automáticas al guardar.
• En Prettier (Settings > Languages & Frameworks > JavaScript > Prettier), marca On save y On 'Reformat Code' action.

El flujo resultante es: al guardar un archivo, primero ESLint corrige lo que puede (--fix) y luego Prettier formatea el resultado. Lo mismo aplica a WebStorm, IntelliJ IDEA Ultimate y al resto de IDEs de JetBrains con soporte para TypeScript (PhpStorm, PyCharm Professional, Rider).

La configuración de ESLint con typescript-eslint es una inversión inicial que mejora significativamente la calidad del código TypeScript a largo plazo. Las reglas type-aware detectan errores que ni el compilador ni las pruebas unitarias capturan facilmente, como promesas no manejadas, usos inseguros de any y expresiones booleanas ambiguas.