TypeScript estricto en un gran proyecto: migración paso a paso sin detener el desarrollo
¿Por qué no puedes simplemente habilitar estricto?
En un proyecto con varios cientos de archivos, "strict": true produce miles de errores. Corregirlos con una rama significa mantener un PR que entra en conflicto con todos durante semanas, que nadie puede revisar adecuadamente. También es imposible detener el desarrollo durante este tiempo. Necesitamos un esquema en el que el nuevo código se escriba inmediatamente de forma estricta y el código antiguo se traduzca en partes.
¿Qué se incluye en estricto?
El indicador strict es un conjunto de comprobaciones independientes, cada una de las cuales se puede habilitar de forma independiente:
noImplicitAny- los parámetros y variables sin un tipo que no se puede inferir se convierten en un error en lugar deany.strictNullChecks-nullyundefinedya no son valores válidos de ningún tipo. Generalmente produce la mayor cantidad de errores y el mayor beneficio.strictFunctionTypes,strictBindCallApply,strictPropertyInitialization,noImplicitThis,alwaysStrict,useUnknownInCatchVariables.
Otro indicador útil no incluido en strict es noUncheckedIndexedAccess: acceder a arr[i] y record[key] devuelve T | undefined. Debe incluirse como un paso separado al final.
Estrategia 1: banderas una a la vez
El esquema más simple para proyectos medianos:
- 1.Habilite indicadores que den pocos errores (
alwaysStrict,strictBindCallApply,noImplicitThis); normalmente esto significa docenas de ediciones. - 2.
noImplicitAny: errores mecánicos, corregidos rápidamente, parcialmente de forma automática. - 3.
strictNullChecks- escenario principal. Es más conveniente hacerlo utilizando la segunda estrategia. - 4.Habilite
strict: truey elimine indicadores individuales.
Cada paso es un pequeño PR independiente que es fácil de incorporar.
Estrategia 2: configuración estricta para archivos traducidos
El tsconfig.json principal sigue siendo no estricto, pero junto a él aparece uno estricto, que verifica solo la parte traducida:
// tsconfig.strict.json
{
"extends": "./tsconfig.json",
"compilerOptions": { "strict": true, "noEmit": true },
"include": [
"src/shared/lib/**/*",
"src/entities/user/**/*",
"next-env.d.ts"
]
}Hay una trampa importante aquí. tsc verifica no solo los archivos de include, sino también todo lo que importan. Si un módulo traducido importa uno no traducido, los errores del módulo no traducido también aparecerán en el resultado. Por lo tanto, se traducen de abajo hacia arriba (primero utilidades y modelos, luego qué los utiliza) y la salida se filtra según la lista de rutas traducidas:
// scripts/check-strict.mjs
import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";
const cfg = JSON.parse(readFileSync("tsconfig.strict.json", "utf8"));
const prefixes = cfg.include.map((p) => p.replace(/\*\*.*$/, ""));
let out = "";
try {
execSync("npx tsc -p tsconfig.strict.json --pretty false", { encoding: "utf8" });
} catch (e) {
out = e.stdout ?? "";
}
const errors = out.split("\n").filter((l) => /error TS\d+/.test(l) && prefixes.some((p) => l.startsWith(p)));
for (const e of errors) console.error(e);
process.exit(errors.length ? 1 : 0);El script va a CI con verificación obligatoria. Agregué la carpeta a include; está protegida contra la regresión para siempre.
Existe una herramienta lista para usar para el mismo enfoque con lógica inversa: typescript-strict-plugin le permite habilitar strict para todo el proyecto marcando archivos no traducidos con un comentario // @ts-strict-ignore, y verificar esto en CI con su comando tsc-strict. Es conveniente cuando ya hay más de la mitad de los archivos traducidos.
Estrategia 3: trinquete según el número de errores
Si es más importante evitar que la situación empeore que arreglarlo todo rápidamente, basta con contar los errores de una ejecución estricta completa y no permitir que su número crezca:
COUNT=$(npx tsc -p tsconfig.strict-all.json --noEmit --pretty false | grep -c "error TS" || true) BASELINE=$(cat .strict-baseline) if [ "$COUNT" -gt "$BASELINE" ]; then echo "strict errors: $COUNT > baseline $BASELINE"; exit 1 fi echo "$COUNT" > .strict-baseline # закоммитьте уменьшение в том же PR
Cada PR no cambia el número o lo disminuye. La herramienta betterer hace lo mismo de una manera más clara: rastrea los errores por archivo, no solo el número total, por lo que una corrección en un lugar no enmascara un nuevo error en otro.
Cómo solucionarlo para que no empeore
El objetivo no es eliminar el subrayado rojo, sino hacer que los tipos sean veraces.
- `!` (aserción no nula) convierte un error de compilación en un error de tiempo de ejecución. Esto sólo es aceptable cuando realmente existe una garantía y se puede explicar. De lo contrario, una verificación explícita con salida anticipada.
- `any` → `unknown` para datos externos (JSON, respuestas API,
catch (e)), y luego limitar mediante comprobaciones o esquema de validación. - `@ts-expect-error` en lugar de `@ts-ignore`. El primero cae cuando el error ya no está presente y evita que las supresiones temporales vivan para siempre. Siempre con un comentario por qué.
- Campos opcionales en modelos. Si un campo en la base de datos es
NOT NULL, no debería ser?en el tipo solo porque es más fácil inicializar el objeto en la prueba.
Las reglas de ESLint @typescript-eslint/no-explicit-any y @typescript-eslint/no-non-null-assertion en modo de error para directorios traducidos evitan que vuelvan los viejos hábitos.
Organización del trabajo
- Pequeñas relaciones públicas en una carpeta, sin mezclarlas con cambios funcionales: son fáciles de revisar y revertir.
- Los archivos nuevos se envían inmediatamente a la zona estricta. De lo contrario, la parte no traducida crece más rápido de lo que disminuye.
- Comience con el código donde los errores son más costosos: trabajar con dinero, derechos de acceso, analizar datos externos.
Cuándo no exagerar
No es necesario traducir los scripts de migración, las utilidades únicas y los prototipos que pronto se eliminarán; exclúyalos de la zona estricta. Y si el proyecto está en modo soporte sin desarrollo activo, el trinquete es suficiente: evitará que empeore, sin requerir un proyecto de migración por separado.