Mejores prácticas de linting y formateo

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de todas las páginas de esta sección.

Usa ESLint 9 Flat Config: Adopta eslint.config.mjs y elimina todos los archivos .eslintrc.* restantes, porque ESLint se revierte al formato heredado si ambos existen y tu flat config se ignora silenciosamente.
Vincula configuraciones con FlatCompat: Las configuraciones preestablecidas de Next.js aún usan las configuraciones de estilo legacy extends, así que envuélvelas con FlatCompat({ baseDirectory: __dirname }) y recrea __dirname mediante fileURLToPath(import.meta.url) en ESM.
Aísla los ignores globales: En flat config, { ignores: [...] } solo actúa como un ignore global cuando es la única clave en su objeto; mezclarlo con rules lo convierte en un filtro por archivo.
Comienza desde next/core-web-vitals: Agrupa eslint-plugin-react, react-hooks, next, import e jsx-a11y, así que rara vez necesitas instalar esos plugins por separado y solo puedes agregar lo que falta.
Elige la gravedad intencionalmente: Usa "error" para las reglas que deseas reforzar (fallar CI, bloquear compilaciones) y reserva "warn" para las reglas hacia las que te estás migrando, ya que las advertencias pasan CI y se acumulan silenciosamente.
Prefiere el no-unused-vars de TypeScript: Desactiva el no-unused-vars base y habilita @typescript-eslint/no-unused-vars con argsIgnorePattern: "^_" para que se comprenda la sintaxis de interfaz/alias de tipo/enum y los conflictos desaparezcan.
Requiere consistent-type-imports: Exige import type { … } para importaciones solo de tipo para que los bundlers puedan borrar completamente los tipos y tu gráfico de tipos se mantenga claramente separado de tu gráfico de valores.
Nunca deshabilites exhaustive-deps globalmente: Mantén react-hooks/exhaustive-deps activado (generalmente como "warn") y suprimelo por línea con // eslint-disable-next-line solo para referencias comprobadamente estables como dispatch o refs.
Ordena las importaciones con separadores de grupo: Configura import/order con categorías agrupadas (builtin, external, internal, parent/sibling, index, type), "newlines-between": "always" y alfabetización; ejecuta eslint --fix una vez y agrega manualmente las líneas en blanco faltantes.
No re-registres plugins incluidos: Instalar un plugin que next/core-web-vitals ya incluye (react, react-hooks, next, import, jsx-a11y) causa registro duplicado y comportamiento de regla inesperado, así que verifica el preestablecimiento primero.
Limita los plugins solo de prueba con files: Restringe eslint-plugin-testing-library detrás de files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"]; aplicado globalmente produce falsos positivos en código que no es de prueba.
Perfila las reglas lentas: Ejecuta TIMING=1 npx eslint . cuando los tiempos de linting suban — cinco o más plugins activos pueden ralentizar significativamente el linting, y las reglas @typescript-eslint conscientes de tipos son 2-5 veces más lentas porque requieren información de tipo completa.
Coloca eslint-config-prettier último: La entrada "prettier" debe ser el elemento final en tu arreglo extends, porque solo desactiva reglas de formateo y cualquier configuración listada después la volverá a habilitar conflictos.
No uses eslint-plugin-prettier: Ejecutar Prettier dentro de ESLint es lento e inunda el editor con cuadrículas rojas por diferencias de formateo puro — ejecuta ESLint y Prettier como comandos separados en su lugar.
Siempre incluye un .prettierignore: Sin él, Prettier camina a través de .next/, node_modules/, archivos de bloqueo y código generado; un archivo de ignore explícito mantiene las ejecuciones rápidas y previene cambios no intencionados.
Lista el plugin de Tailwind último: prettier-plugin-tailwindcss debe sentarse al final del arreglo plugins de Prettier o entrará en conflicto con otros plugins de Prettier y el ordenamiento de clases se rompe.
Fija endOfLine a lf: Establece "endOfLine": "lf" en .prettierrc y configura git config --global core.autocrlf input para que los colaboradores de Windows no envíen archivos CRLF que fallen prettier --check en CI de Linux.
Confirma los ajustes de equipo de .vscode: Verifica en .vscode/settings.json y .vscode/extensions.json (no launch.json o *.code-workspace) para que cada desarrollador herede el mismo comportamiento de format-on-save, ESLint y extensiones recomendadas.
Establece defaultFormatter por idioma: Declara editor.defaultFormatter tanto globalmente como por idioma ([typescript], [typescriptreact], [json]) para evitar que VS Code elija un formateador aleatorio cuando hay varios instalados.
Usa el TypeScript del espacio de trabajo: Apunta typescript.tsdk a node_modules/typescript/lib para que la verificación de tipo del editor coincida con la versión que tsc usa en CI, eliminando la desviación de tipo "works on my machine".
Habilita strict más flags adicionales: Activa "strict": true para las ocho comprobaciones incluidas y agrega noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch y verbatimModuleSyntax porque no están incluidas en strict.
Adopta strict incrementalmente: En una base de código heredada, mantén "strict": false e habilita strictNullChecks primero, luego noImplicitAny, usando // @ts-expect-error (no @ts-ignore) para que las supresiones fallen automáticamente una vez que se resuelve el problema subyacente.
Ejecuta tsc --noEmit en CI: TypeScript detecta quiebres de tipo entre archivos que ESLint no puede (por ejemplo, eliminar un miembro de unión de un tipo compartido); agrega "type-check": "tsc --noEmit" y confía en incremental: true más un .tsbuildinfo en caché para velocidad.
Instala Husky mediante prepare: Pon "prepare": "husky" en package.json para que los hooks de pre-confirmación se instalen automáticamente después de npm install, y mantén los hooks rápidos ejecutando solo lint-staged (con eslint --fix --no-warn-ignored) — nunca tsc completo.
Convierte CI en la red de seguridad: Ejecuta lint, prettier --check y tsc --noEmit en GitHub Actions usando npm ci para instalaciones deterministas, una versión de Node fija coincidente, un grupo de concurrency con cancel-in-progress: true y reglas de protección de rama que requieran que el trabajo pase antes de fusionar.

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de todas las páginas de esta sección.

Usa ESLint 9 Flat Config: Adopta eslint.config.mjs y elimina todos los archivos .eslintrc.* restantes, porque ESLint se revierte al formato heredado si ambos existen y tu flat config se ignora silenciosamente.

Vincula configuraciones con FlatCompat: Las configuraciones preestablecidas de Next.js aún usan las configuraciones de estilo legacy extends, así que envuélvelas con FlatCompat({ baseDirectory: __dirname }) y recrea __dirname mediante fileURLToPath(import.meta.url) en ESM.

Aísla los ignores globales: En flat config, { ignores: [...] } solo actúa como un ignore global cuando es la única clave en su objeto; mezclarlo con rules lo convierte en un filtro por archivo.

Comienza desde next/core-web-vitals: Agrupa eslint-plugin-react, react-hooks, next, import e jsx-a11y, así que rara vez necesitas instalar esos plugins por separado y solo puedes agregar lo que falta.

Elige la gravedad intencionalmente: Usa "error" para las reglas que deseas reforzar (fallar CI, bloquear compilaciones) y reserva "warn" para las reglas hacia las que te estás migrando, ya que las advertencias pasan CI y se acumulan silenciosamente.

Prefiere el no-unused-vars de TypeScript: Desactiva el no-unused-vars base y habilita @typescript-eslint/no-unused-vars con argsIgnorePattern: "^_" para que se comprenda la sintaxis de interfaz/alias de tipo/enum y los conflictos desaparezcan.

Requiere consistent-type-imports: Exige import type { … } para importaciones solo de tipo para que los bundlers puedan borrar completamente los tipos y tu gráfico de tipos se mantenga claramente separado de tu gráfico de valores.

Nunca deshabilites exhaustive-deps globalmente: Mantén react-hooks/exhaustive-deps activado (generalmente como "warn") y suprimelo por línea con // eslint-disable-next-line solo para referencias comprobadamente estables como dispatch o refs.

Ordena las importaciones con separadores de grupo: Configura import/order con categorías agrupadas (builtin, external, internal, parent/sibling, index, type), "newlines-between": "always" y alfabetización; ejecuta eslint --fix una vez y agrega manualmente las líneas en blanco faltantes.

No re-registres plugins incluidos: Instalar un plugin que next/core-web-vitals ya incluye (react, react-hooks, next, import, jsx-a11y) causa registro duplicado y comportamiento de regla inesperado, así que verifica el preestablecimiento primero.

Limita los plugins solo de prueba con files: Restringe eslint-plugin-testing-library detrás de files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"]; aplicado globalmente produce falsos positivos en código que no es de prueba.

Perfila las reglas lentas: Ejecuta TIMING=1 npx eslint . cuando los tiempos de linting suban — cinco o más plugins activos pueden ralentizar significativamente el linting, y las reglas @typescript-eslint conscientes de tipos son 2-5 veces más lentas porque requieren información de tipo completa.

Coloca eslint-config-prettier último: La entrada "prettier" debe ser el elemento final en tu arreglo extends, porque solo desactiva reglas de formateo y cualquier configuración listada después la volverá a habilitar conflictos.

No uses eslint-plugin-prettier: Ejecutar Prettier dentro de ESLint es lento e inunda el editor con cuadrículas rojas por diferencias de formateo puro — ejecuta ESLint y Prettier como comandos separados en su lugar.

Siempre incluye un .prettierignore: Sin él, Prettier camina a través de .next/, node_modules/, archivos de bloqueo y código generado; un archivo de ignore explícito mantiene las ejecuciones rápidas y previene cambios no intencionados.

Lista el plugin de Tailwind último: prettier-plugin-tailwindcss debe sentarse al final del arreglo plugins de Prettier o entrará en conflicto con otros plugins de Prettier y el ordenamiento de clases se rompe.

Fija endOfLine a lf: Establece "endOfLine": "lf" en .prettierrc y configura git config --global core.autocrlf input para que los colaboradores de Windows no envíen archivos CRLF que fallen prettier --check en CI de Linux.

Confirma los ajustes de equipo de .vscode: Verifica en .vscode/settings.json y .vscode/extensions.json (no launch.json o *.code-workspace) para que cada desarrollador herede el mismo comportamiento de format-on-save, ESLint y extensiones recomendadas.

Establece defaultFormatter por idioma: Declara editor.defaultFormatter tanto globalmente como por idioma ([typescript], [typescriptreact], [json]) para evitar que VS Code elija un formateador aleatorio cuando hay varios instalados.

Usa el TypeScript del espacio de trabajo: Apunta typescript.tsdk a node_modules/typescript/lib para que la verificación de tipo del editor coincida con la versión que tsc usa en CI, eliminando la desviación de tipo "works on my machine".

Habilita strict más flags adicionales: Activa "strict": true para las ocho comprobaciones incluidas y agrega noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch y verbatimModuleSyntax porque no están incluidas en strict.

Adopta strict incrementalmente: En una base de código heredada, mantén "strict": false e habilita strictNullChecks primero, luego noImplicitAny, usando // @ts-expect-error (no @ts-ignore) para que las supresiones fallen automáticamente una vez que se resuelve el problema subyacente.

Ejecuta tsc --noEmit en CI: TypeScript detecta quiebres de tipo entre archivos que ESLint no puede (por ejemplo, eliminar un miembro de unión de un tipo compartido); agrega "type-check": "tsc --noEmit" y confía en incremental: true más un .tsbuildinfo en caché para velocidad.

Instala Husky mediante prepare: Pon "prepare": "husky" en package.json para que los hooks de pre-confirmación se instalen automáticamente después de npm install, y mantén los hooks rápidos ejecutando solo lint-staged (con eslint --fix --no-warn-ignored) — nunca tsc completo.

Convierte CI en la red de seguridad: Ejecuta lint, prettier --check y tsc --noEmit en GitHub Actions usando npm ci para instalaciones deterministas, una versión de Node fija coincidente, un grupo de concurrency con cancel-in-progress: true y reglas de protección de rama que requieran que el trabajo pase antes de fusionar.

Mejores prácticas de linting y formateo

Buscar en la documentación

Mejores prácticas de linting y formateo