Instalar TypeScript y compilar tu primer archivo

Para trabajar con TypeScript en tu ordenador necesitas dos cosas: Node.js, que trae el gestor de paquetes npm, y el compilador de TypeScript, tsc. En esta lección vas a instalarlo en un proyecto, compilar tu primer archivo, crear el archivo de configuración tsconfig.json y conocer las formas modernas de ejecutar TypeScript sin compilar a mano: Node.js, tsx y Vite.

Node.js y npm

TypeScript se instala con npm (el gestor de paquetes de Node.js). Si ya seguiste la lección de Node.js, lo tienes. Compruébalo en la terminal:

node -v
npm -v

Si ves dos números de versión (por ejemplo, v22.22.2 y 10.9.7), todo está listo. Si no, descarga la versión LTS (la de soporte largo) desde nodejs.org e instálala con las opciones por defecto. Cierra y vuelve a abrir la terminal después de instalar.

Consejo: usa Node.js 22 o posterior (lo ideal, la LTS más reciente). Además de recibir actualizaciones de seguridad, puede ejecutar archivos .ts directamente, como verás más abajo.

Crear un proyecto e instalar TypeScript

Crea una carpeta para el proyecto, entra en ella y prepara el package.json, el archivo que describe el proyecto y sus dependencias:

mkdir gimnasio-ts
cd gimnasio-ts
npm init -y

Ahora instala TypeScript en el proyecto:

npm install -D typescript

La opción -D (de dev) lo guarda como dependencia de desarrollo: algo que necesitas mientras programas, pero no cuando el programa funciona en producción. Tiene sentido, porque lo que se ejecuta al final es JavaScript, no TypeScript.

Para usar el compilador instalado en el proyecto se antepone npx, que busca el programa en la carpeta node_modules:

npx tsc --version
# Version 5.9.3

Nota: también se puede instalar de forma global con npm install -g typescript y usar tsc sin npx. No es mala idea para experimentar, pero en proyectos reales es mejor instalarlo en cada uno: así todo el equipo usa la misma versión y el proyecto funciona en cualquier ordenador con un simple npm install.

Compilar tu primer archivo

Crea un archivo saludo.ts:

const nombre: string = "Marta";
const sesiones: number = 3;

console.log(`${nombre} tiene ${sesiones} sesiones esta semana`);
// Marta tiene 3 sesiones esta semana

Compílalo pasando el nombre del archivo a tsc:

npx tsc saludo.ts

Si no hay errores, no muestra nada, pero aparece un archivo nuevo, saludo.js, junto al original:

"use strict";
const nombre = "Marta";
const sesiones = 3;
console.log(`${nombre} tiene ${sesiones} sesiones esta semana`);

Los tipos han desaparecido. La primera línea, "use strict", activa el modo estricto de JavaScript; la añade el compilador cuando las comprobaciones estrictas están activas. Ahora puedes ejecutar el resultado con Node.js:

node saludo.js
# Marta tiene 3 sesiones esta semana

Cuando hay errores

Cambia el archivo para provocar un error:

const nombre: string = "Marta";
let sesiones: number = 3;
sesiones = "tres";
// Error: Type 'string' is not assignable to type 'number'.

Al compilar verás algo así:

saludo.ts:3:1 - error TS2322: Type 'string' is not assignable to type 'number'.

3 sesiones = "tres";
  ~~~~~~~~

Found 1 error in saludo.ts:3

El mensaje te dice el archivo, la línea y la columna (3:1), un código de error (TS2322) y la explicación. Los mensajes siempre están en inglés; con la práctica reconocerás enseguida los más frecuentes.

Cuidado: aunque haya errores, tsc genera el .js igualmente. Es así a propósito, para poder migrar código poco a poco, pero no te fíes: si el compilador se queja, corrige antes de seguir. Si prefieres que no genere nada cuando hay errores, activa la opción noEmitOnError.

Modo vigilancia: --watch

Compilar a mano después de cada cambio es pesado. Con --watch, tsc se queda vigilando y recompila cada vez que guardas:

npx tsc saludo.ts --watch

7:56:18 PM - Starting compilation in watch mode...

7:56:19 PM - Found 0 errors. Watching for file changes.

Déjalo abierto en una terminal mientras trabajas y páralo con Ctrl + C.

El archivo tsconfig.json

En un proyecto real no compilas archivo a archivo. Lo normal es tener un tsconfig.json en la raíz: un archivo de configuración que le dice a tsc qué archivos compilar, dónde dejar el resultado y qué comprobaciones hacer. Se crea con:

npx tsc --init

El archivo generado trae bastantes opciones con comentarios explicativos. Para empezar, te basta con entender estas:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist",
    "skipLibCheck": true
  },
  "include": ["src"]
}

Opción	Qué hace
target	Versión de JavaScript que se genera. es2022 sirve para navegadores y Node actuales
module	Sistema de módulos del resultado. nodenext para Node.js; con Vite verás esnext
strict	Activa todas las comprobaciones estrictas. Déjalo siempre en true
rootDir	Carpeta donde están tus .ts
outDir	Carpeta donde se guardan los .js generados
skipLibCheck	No revisa los tipos de las librerías de node_modules; compila más rápido
include	Qué archivos forman parte del proyecto

Con esta configuración, organiza el proyecto así:

gimnasio-ts/
├── package.json
├── tsconfig.json
├── src/
│   └── saludo.ts
└── dist/          ← lo crea tsc
    └── saludo.js

Y ahora compilas sin indicar archivos: tsc busca el tsconfig.json y compila todo el proyecto.

npx tsc
node dist/saludo.js
# Marta tiene 3 sesiones esta semana

El modo vigilancia funciona igual: npx tsc --watch.

Cuidado: si escribes npx tsc saludo.ts (con un archivo concreto), tsc no usa el tsconfig.json. En TypeScript 5 lo ignora sin avisar, y en TypeScript 6 da el error TS5112. Dentro de un proyecto, usa siempre npx tsc a secas.

Sobre strict: activa varias comprobaciones a la vez, entre ellas que no puedas dejar parámetros sin tipo o que tengas que tener en cuenta los valores null y undefined. En TypeScript 6 viene activado por defecto, pero en la versión 5 no, así que escríbelo siempre de forma explícita. Todo este curso da por hecho "strict": true. En Módulos y tsconfig verás más opciones.

Scripts de npm

Para no recordar los comandos, añádelos a la sección scripts del package.json:

{
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "check": "tsc --noEmit"
  }
}

Así escribes npm run build para compilar, npm run dev para trabajar con vigilancia y npm run check para solo comprobar tipos sin generar archivos (eso hace --noEmit).

Ejecutar TypeScript sin compilar

Compilar y luego ejecutar son dos pasos. Hoy hay formas de hacerlo en uno.

Con Node.js directamente

Las versiones recientes de Node.js ejecutan archivos .ts quitando los tipos al vuelo (type stripping):

node src/saludo.ts
# Marta tiene 3 sesiones esta semana

• En Node 22.6 apareció con la opción --experimental-strip-types.
• Desde Node 23.6 (y en Node 22.18 y posteriores) funciona sin opciones.

Tiene dos limitaciones importantes:

1. No comprueba tipos, solo los borra. Un archivo con errores de tipos se ejecuta igualmente. Por eso se combina con tsc --noEmit, que comprueba sin generar archivos.
2. Solo admite sintaxis que se pueda borrar sin más. Cosas como los enum (que generan código) dan error: TypeScript enum is not supported in strip-only mode. Lo verás en la lección de Enums y literales.

Además, al importar otros archivos hay que escribir la extensión .ts: import { precio } from "./tarifas.ts".

Con tsx

tsx es una herramienta muy usada que ejecuta TypeScript en cualquier versión de Node y admite toda la sintaxis:

npm install -D tsx
npx tsx src/saludo.ts
npx tsx watch src/saludo.ts

Con watch, vuelve a ejecutar el programa cada vez que guardas. Igual que Node, no comprueba tipos: es para ejecutar rápido mientras desarrollas.

Consejo: un flujo de trabajo cómodo es ejecutar con node o tsx y dejar en otra terminal npx tsc --noEmit --watch para ver los errores de tipos. Y en todo caso, el editor ya te los marca en rojo mientras escribes.

TypeScript en Visual Studio Code

VS Code trae TypeScript integrado: no hace falta ninguna extensión. Al abrir un archivo .ts:

• Los errores aparecen subrayados en rojo. Pasa el ratón por encima para leer el mensaje.
• El panel Problemas (Ctrl + Mayús + M) lista todos los errores de los archivos abiertos.
• Al pasar el ratón sobre una variable o función ves su tipo. Es la mejor forma de aprender qué deduce TypeScript.
• F2 sobre un nombre lo renombra en todo el proyecto, y F12 te lleva a donde está definido.

Si el proyecto tiene TypeScript instalado, VS Code puede usar esa versión en lugar de la suya: abre la paleta de comandos (Ctrl + Mayús + P) y busca TypeScript: Select TypeScript Version.

Nota: VS Code usa la configuración de tu tsconfig.json. Si ves errores distintos en el editor y en la terminal, revisa que el archivo esté dentro de las carpetas de include.

TypeScript en proyectos con Vite

Para webs con HTML, CSS y TypeScript, lo más práctico es Vite, una herramienta que levanta un servidor de desarrollo y prepara la web para publicarla. Crea un proyecto con la plantilla de TypeScript:

npm create vite@latest mi-tienda -- --template vanilla-ts
cd mi-tienda
npm install
npm run dev

La plantilla ya trae tsconfig.json y una carpeta src/ con un main.ts. En el HTML se enlaza el archivo .ts tal cual:

<script type="module" src="/src/main.ts"></script>

Vite quita los tipos al vuelo, así que la página se actualiza al instante cuando guardas. Pero, igual que Node y tsx, no comprueba tipos mientras desarrollas: confía en los avisos del editor. Al ejecutar npm run build, el script de la plantilla lanza primero tsc (para comprobar) y después vite build (para generar la web). Si hay errores de tipos, el build se detiene.

Las plantillas de React (react-ts), Vue (vue-ts) y otros frameworks funcionan igual.

Errores frecuentes

• tsc: command not found: has instalado TypeScript en el proyecto pero lo llamas sin npx. Usa npx tsc o mételo en un script de npm.
• Pasar un archivo a tsc dentro de un proyecto: npx tsc src/app.ts ignora el tsconfig.json (o da error en TypeScript 6). Usa npx tsc sin argumentos.
• Pensar que Node, tsx o Vite te avisan de los errores de tipos: solo borran los tipos. Comprueba con el editor o con tsc --noEmit.
• Ejecutar el .ts con un Node antiguo: Node 20 (o un Node 22 anterior al 22.18 sin la opción experimental) no reconoce los archivos .ts y da el error Unknown file extension ".ts". Actualiza a la LTS o usa tsx.
• Subir la carpeta dist o node_modules a Git: se generan solas. Añádelas al .gitignore.
• Quitar strict para que desaparezcan los errores: los errores siguen ahí, solo dejas de verlos. Aprende a resolverlos.

Resumen

Comando o archivo	Para qué sirve
npm install -D typescript	Instala el compilador en el proyecto
npx tsc archivo.ts	Compila un archivo suelto a .js
npx tsc --init	Crea el tsconfig.json
npx tsc	Compila todo el proyecto según tsconfig.json
npx tsc --watch	Recompila al guardar
npx tsc --noEmit	Solo comprueba tipos, sin generar archivos
strict, target, module, rootDir, outDir	Opciones básicas del tsconfig.json
node archivo.ts	Ejecuta quitando tipos (Node 22.18+ / 23.6+), sin comprobarlos
npx tsx archivo.ts	Ejecuta TypeScript en cualquier Node, sin comprobar tipos
Vite vanilla-ts	Proyecto web con TypeScript listo para usar

En la siguiente lección empiezas con los tipos de verdad: Tipos básicos.