Generador de tsconfig.json
Elige una plantilla de partida, ajusta las opciones del compilador y obtén un tsconfig.json limpio con comentarios. Cada opción que activas se explica con palabras sencillas, y los ajustes en conflicto, como una combinación incorrecta de module y moduleResolution, se señalan antes de que tsc se queje.
Última actualización:
tsconfig.json
Qué hace cada opción
Cómo usar Generador de tsconfig.json
- Elige una plantilla que se ajuste a tu proyecto: Node.js ESM o CommonJS, una app React + Vite, una librería publicable o la configuración más estricta.
- Ajusta el lenguaje y los módulos: el target de JavaScript, las libs integradas, el formato de módulos y la estrategia de resolución, y el modo JSX.
- Elige las comprobaciones de tipos y las opciones de salida, como strict, noUncheckedIndexedAccess, outDir, archivos de declaraciones y source maps.
- Añade alias de rutas como
@/* ./src/*y define las carpetas de include/exclude. - Lee las notas y explicaciones y después copia o descarga tsconfig.json en la raíz de tu proyecto y ejecuta
npx tsc --noEmit.
Cómo combinar module y moduleResolution
La mayoría de los errores confusos de tsconfig vienen de una combinación de module y moduleResolution que no encaja con cómo se ejecuta realmente el código. Estas son las combinaciones que recomienda TypeScript:
| Proyecto | module | moduleResolution | Extras habituales |
|---|---|---|---|
| Node.js ejecuta el JS compilado (ESM o CJS) | NodeNext | NodeNext (u omitir) | outDir, types: ["node"], extensiones .js en los imports |
| App compilada con Vite, webpack, esbuild, Parcel | ESNext o Preserve | Bundler | noEmit, isolatedModules, jsx |
| Proyecto Node.js antiguo solo con CommonJS | CommonJS | Node10 | esModuleInterop |
| Librería publicada en npm | NodeNext | NodeNext | declaration, declarationMap, sourceMap |
| Código ejecutado con tsx, ts-node, Bun o Deno | Preserve o ESNext | Bundler | noEmit, allowImportingTsExtensions |
Cómo elegir un target
| target | Sintaxis destacada que se conserva tal cual | Adecuado para |
|---|---|---|
ES2017 | async / await | Navegadores antiguos y Node 8+ |
ES2020 | encadenamiento opcional ?., nullish ??, BigInt | Navegadores actualizados, Node 14+ |
ES2022 | campos de clase, #private, await de nivel superior, .at() | Node 16.11+ / 18+, navegadores actuales |
ES2023+ | findLast, toSorted de arrays y API similares (mediante lib) | Node 20+ y navegadores recientes |
ESNext | Todo lo que admite la versión de TypeScript | Código que otra herramienta transpila después |
Recuerda que target solo cambia la sintaxis. Las API de tiempo de ejecución como Array.prototype.at no reciben polyfill; lib solo declara que existen.
Consejos para una configuración sana
- Empieza en modo estricto. Activar
strictdesde el primer día cuesta poco; añadirlo a una base de código grande ya existente puede sacar a la luz cientos de errores. - Usa extends para la configuración compartida. Los monorepos suelen tener un
tsconfig.base.jsony cada paquete usa"extends": "../../tsconfig.base.json". - Comprueba qué se incluye.
npx tsc --listFilesOnlymuestra todos los archivos del programa ynpx tsc --showConfigmuestra las opciones finales combinadas. - Separa la compilación de la comprobación de tipos. En apps con bundler, deja que el bundler genere el JavaScript y ejecuta
tsc --noEmiten CI para detectar errores de tipos.
Preguntas frecuentes
¿Qué es tsconfig.json?
tsconfig.json es el archivo de configuración de un proyecto TypeScript. Sus compilerOptions indican al compilador de TypeScript (tsc) y a tu editor qué versión de JavaScript generar, cómo se resuelven los módulos y qué comprobaciones de tipos ejecutar, mientras que include y exclude deciden qué archivos pertenecen al proyecto.
¿Qué moduleResolution debo usar?
Usa NodeNext (con module NodeNext) para código que Node.js ejecuta directamente, porque sigue las reglas reales de Node, incluidos los exports de package.json y las extensiones .js obligatorias. Usa Bundler (con module ESNext o Preserve) para apps compiladas con Vite, webpack, esbuild o herramientas similares. Node10 es el algoritmo CommonJS heredado e ignora los mapas exports.
¿Qué activa strict: true?
strict activa una familia de comprobaciones: strictNullChecks, noImplicitAny, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, useUnknownInCatchVariables y alwaysStrict. Las nuevas opciones strict que se añadan en versiones posteriores de TypeScript se incluyen automáticamente. Las comprobaciones adicionales como noUncheckedIndexedAccess no forman parte de strict y deben activarse por separado.
¿Por qué mis alias de rutas funcionan en el editor pero fallan en tiempo de ejecución?
paths solo indica a TypeScript cómo encontrar los tipos; tsc no reescribe las rutas de import en el JavaScript generado. Configura el mismo alias en tu bundler (por ejemplo, resolve.alias de Vite), usa imports de package.json con alias #, o una ayuda en tiempo de ejecución como tsconfig-paths.
¿Necesito baseUrl para paths?
No. Desde TypeScript 4.1, paths se puede usar sin baseUrl y se resuelve en relación con el archivo tsconfig.json. Además, baseUrl hace que cualquier import sin ruta relativa se pueda resolver desde esa carpeta, lo que puede ocultar errores, así que los proyectos nuevos suelen omitirlo.
¿Por qué TypeScript me pide extensiones .js en los imports?
Con module y moduleResolution en Node16 o NodeNext, los archivos de módulos ES siguen las reglas de Node.js, que exigen rutas relativas completas. Escribes import './util.js' aunque el archivo fuente sea util.ts, porque ese es el archivo que existirá después de la compilación.
¿Puede un tsconfig.json contener comentarios?
Sí. TypeScript lee tsconfig.json como JSON con comentarios, así que se aceptan comentarios // y /* */ y comas finales. Algunas otras herramientas que leen el archivo como JSON estricto pueden no aceptar comentarios; desactiva la opción Comentarios si necesitas JSON puro.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.