¿Qué es tsconfig.json?
El archivo tsconfig.json es el archivo de configuración principal de TypeScript. Define cómo el compilador debe procesar tus archivos .ts y qué reglas de verificación debe aplicar.
Crearlo: Ejecuta tsc --init en tu terminal
🏗️ Estructura Básica
{
"compilerOptions": {
/* Opciones del compilador */
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
include
Especifica qué archivos deben ser incluidos en la compilación
Ejemplo: ["src/**/*"] incluye todos los archivos en src/
exclude
Especifica qué archivos deben ser excluidos de la compilación
Ejemplo: ["node_modules", "dist"] excluye estas carpetas
⚙️ Opciones del Compilador (compilerOptions)
Opciones Básicas
target
"ES2020" | "ES2015" | "ES5" | "ESNext"
Especifica la versión de JavaScript a la que se compilará el código TypeScript
💡 Usa ES2020 o superior para proyectos modernos, ES5 para navegadores antiguos
module
"commonjs" | "ES2015" | "ESNext"
Define el sistema de módulos a utilizar
💡 commonjs para Node.js, ES2015/ESNext para módulos modernos
lib
["ES2020", "DOM"]
Especifica las librerías de tipos que estarán disponibles
💡 Incluye "DOM" para proyectos de navegador, omítelo para Node.js
outDir
"./dist" | "./build"
Carpeta donde se guardarán los archivos JavaScript compilados
💡 Mantén el código compilado separado del código fuente
rootDir
"./src"
Carpeta raíz de tus archivos TypeScript fuente
💡 Define la estructura de carpetas para la salida
Modo Estricto (Strict Mode)
💪 Recomendación
Activa "strict": true para habilitar todas las verificaciones estrictas. Esto te ayudará a escribir código más seguro y confiable.
strict
true | false
Activa todas las opciones de verificación estricta
💡 Recomendado: true para proyectos nuevos
noImplicitAny
true | false
Genera error cuando una variable tiene tipo 'any' implícito
💡 Fuerza a declarar tipos explícitos, mejora la seguridad del código
strictNullChecks
true | false
null y undefined deben ser manejados explícitamente
💡 Previene errores comunes de "Cannot read property of null"
strictFunctionTypes
true | false
Verificación estricta de tipos en funciones
💡 Asegura que los parámetros de función sean correctos
noUnusedLocals
true | false
Error si hay variables locales no utilizadas
💡 Mantiene el código limpio y sin código muerto
noUnusedParameters
true | false
Error si hay parámetros de función no utilizados
💡 Identifica parámetros innecesarios
Rutas y Módulos
baseUrl
"./" | "./src"
Directorio base para resolver rutas de módulos no relativos
💡 Permite importar desde rutas absolutas
paths
{ "@/*": ["src/*"] }
Mapeo de alias de rutas personalizadas
💡 Ejemplo: import { Usuario } from '@/models/Usuario'
📝 Ejemplo de configuración de rutas
{
"compilerOptions": {
"baseUrl": "./",
"paths": {
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"],
"@models/*": ["src/models/*"]
}
}
}
moduleResolution
"node" | "classic"
Estrategia para resolver módulos
💡 Usa "node" para proyectos modernos
esModuleInterop
true | false
Facilita la importación de módulos CommonJS
💡 Permite: import express from 'express' en lugar de import * as express
allowSyntheticDefaultImports
true | false
Permite importaciones default sintéticas
💡 Mejora compatibilidad con librerías que no tienen export default
resolveJsonModule
true | false
Permite importar archivos .json
💡 Ejemplo: import config from './config.json'
Opciones Avanzadas
declaration
true | false
Genera archivos .d.ts con definiciones de tipos
💡 Importante para crear librerías que otros usarán
sourceMap
true | false
Genera archivos .map para debugging
💡 Permite depurar código TypeScript en el navegador
removeComments
true | false
Elimina comentarios del código compilado
💡 Reduce el tamaño de los archivos finales
skipLibCheck
true | false
No verifica tipos en archivos de definición (.d.ts) de node_modules
💡 Acelera significativamente la compilación
forceConsistentCasingInFileNames
true | false
Asegura consistencia en mayúsculas/minúsculas en nombres de archivo
💡 Previene problemas entre sistemas operativos (Windows vs Linux/Mac)
allowJs
true | false
Permite incluir archivos JavaScript en el proyecto
💡 Útil para migración gradual de JavaScript a TypeScript
checkJs
true | false
Verifica errores de tipo en archivos .js
💡 Añade verificación de tipos a código JavaScript existente
jsx
"react" | "react-jsx" | "preserve"
Modo de compilación para JSX (React)
💡 "react-jsx" para React 17+, "react" para versiones anteriores
📦 Ejemplos de Configuración Completa
Proyecto Node.js / Backend
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"moduleResolution": "node",
"sourceMap": true,
"declaration": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
Proyecto React / Frontend
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"jsx": "react-jsx",
"module": "ESNext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"allowImportingTsExtensions": true,
"isolatedModules": true,
"noEmit": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"allowSyntheticDefaultImports": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src"],
"exclude": ["node_modules"]
}
Librería / Package NPM
{
"compilerOptions": {
"target": "ES2015",
"module": "commonjs",
"lib": ["ES2015"],
"declaration": true,
"declarationMap": true,
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"removeComments": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
💡 Mejores Prácticas
✅ Siempre activa strict mode
Configura "strict": true desde el inicio. Te ahorrará dolores de cabeza futuros.
✅ Organiza tus archivos
Usa rootDir y outDir para mantener código fuente y compilado separados.
✅ Usa paths para imports limpios
Configura alias de rutas para evitar imports como: ../../../components/Button
✅ Habilita skipLibCheck
Acelera la compilación sin sacrificar seguridad en tu propio código.
⚠️ Cuidado con allowJs sin checkJs
Si permites archivos JS, considera activar checkJs para mantener consistencia en verificación de tipos.
⚠️ No uses "any" por defecto
Con noImplicitAny activo, TypeScript te forzará a ser explícito con tus tipos.
🚀 Comandos Útiles
tsc --init
Crea un nuevo archivo tsconfig.json con opciones comentadas
tsc
Compila el proyecto usando la configuración de tsconfig.json
tsc --watch
Compila y observa cambios en tiempo real
tsc --noEmit
Solo verifica errores sin generar archivos JavaScript
tsc --showConfig
Muestra la configuración efectiva que está usando TypeScript