Instalación y configuración de TypeScript

Instalación de TypeScript

TypeScript se distribuye como un paquete de npm, por lo que el requisito previo es tener Node.js instalado. Node.js incluye npm (Node Package Manager) de forma automática. Para verificar que ambos están disponibles:

node --versión
npm --versión

Si estos comandos muestran las versiones instaladas, el entorno está listo para instalar TypeScript.

Instalación global

La instalación global permite utilizar el compilador tsc desde cualquier directorio del sistema:

npm install -g typescript

Para verificar la instalación:

tsc --versión

Este comando muestra la versión del compilador. La instalación global es conveniente para experimentar y crear proyectos rapidamente, pero en proyectos profesionales se recomienda la instalación local.

Instalación local al proyecto

En un proyecto real, TypeScript se instala como dependencia de desarrollo. Esto garantiza que todos los miembros del equipo utilicen la misma versión del compilador:

mkdir mi-proyecto-ts
cd mi-proyecto-ts
npm init -y
npm install --save-dev typescript

Con la instalación local, el compilador se invoca a través de npx:

npx tsc --versión

La instalación local como dependencia de desarrollo es la práctica recomendada en proyectos profesionales. Evita conflictos de versión entre distintos proyectos en la misma maquina.

Primer archivo TypeScript

Con TypeScript instalado, el siguiente paso es crear un archivo .ts, compilarlo y ejecutar el resultado.

Crear el archivo fuente

Crea un archivo llamado hola.ts con el siguiente contenido:

function saludar(nombre: string): string {
  return `Hola, ${nombre}. Bienvenido a TypeScript.`;
}

const usuario: string = "Desarrollador";
console.log(saludar(usuario));

type Persona = {
  nombre: string;
  apellido: string;
  edad: number;
};

const dev: Persona = {
  nombre: "Ana",
  apellido: "Garcia",
  edad: 28
};

console.log(`${dev.nombre} ${dev.apellido}, ${dev.edad} anos`);

Este archivo utiliza anotaciones de tipo en la función y en las variables, además de un type alias para definir la estructura de un objeto.

Compilar con tsc

El compilador tsc transforma el archivo .ts en .js:

tsc hola.ts

Este comando genera un archivo hola.js en el mismo directorio. El JavaScript resultante no contiene ninguna anotación de tipo:

function saludar(nombre) {
  return "Hola, " + nombre + ". Bienvenido a TypeScript.";
}
var usuario = "Desarrollador";
console.log(saludar(usuario));
var dev = {
  nombre: "Ana",
  apellido: "Garcia",
  edad: 28
};
console.log(dev.nombre + " " + dev.apellido + ", " + dev.edad + " anos");

El formato del JavaScript generado depende de la configuración de target del compilador. Sin configuración explícita, tsc utiliza un target conservador.

Ejecutar el resultado

El archivo JavaScript generado se ejecuta con Node.js:

node hola.js

La salida será:

Hola, Desarrollador. Bienvenido a TypeScript.
Ana Garcia, 28 anos

Detección de errores en compilación

Si el código contiene un error de tipos, tsc lo detecta durante la compilación:

function calcular(precio: number, cantidad: number): number {
  return precio * cantidad;
}

// Error: Argument of type 'string' is not assignable to parameter of type 'number'
const total = calcular("diez", 5);
console.log(total);

El compilador muestra el error y no genera el archivo .js (dependiendo de la configuración). Esto garantiza que solo se ejecute código que ha superado la verificación de tipos.

Ejecución directa con ts-node y tsx

Compilar manualmente con tsc y luego ejecutar con node puede resultar tedioso durante el desarrollo. Herramientas como ts-node y tsx permiten ejecutar archivos TypeScript directamente.

ts-node

ts-node compila y ejecuta TypeScript en un solo paso:

npm install --save-dev ts-node

Para ejecutar un archivo:

npx ts-node hola.ts

ts-node compila el archivo en memoria y lo ejecuta inmediatamente sin generar un archivo .js en disco.

tsx

tsx es una alternativa más moderna y rápida a ts-node, basada en esbuild:

npm install --save-dev tsx

Para ejecutar un archivo:

npx tsx hola.ts

tsx ofrece tiempos de inicio más rápidos que ts-node al utilizar esbuild para la transpilación. Es especialmente útil durante el desarrollo cuando se ejecutan archivos con frecuencia.

Modo watch con tsx

tsx incluye un modo watch que recompila y reejecuta el archivo cada vez que se detectan cambios:

npx tsx watch hola.ts

Este modo es ideal durante el desarrollo activo. Cada vez que se guarda el archivo, se ejecuta automáticamente.

Configuración básica con tsconfig.json

El archivo tsconfig.json centraliza la configuración del compilador TypeScript para todo el proyecto. En lugar de pasar opciones por línea de comandos, se definen una vez en este archivo.

Generar el archivo

El compilador puede generar un tsconfig.json con valores predeterminados:

npx tsc --init

Este comando crea el archivo con opciones comentadas que sirven como referencia. Una configuración básica funcional tiene este aspecto:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Opciones fundamentales

Las opciones más importantes de una configuración inicial son:

• target: versión de JavaScript de salida. ES2022 es una buena opción para entornos modernos.
• module: sistema de módulos del JavaScript generado. NodeNext para proyectos Node.js.
• strict: activa todas las comprobaciones estrictas de tipos. Siempre recomendado para proyectos nuevos.
• outDir: directorio donde se generan los archivos .js.
• rootDir: directorio donde se encuentran los archivos fuente .ts.
• include: patrones de archivos a incluir en la compilación.
• exclude: patrones de archivos a excluir.

Estructura de proyecto recomendada

Con el tsconfig.json configurado, la estructura del proyecto queda organizada:

mi-proyecto-ts/
  src/
    index.ts
    utils.ts
  dist/
    index.js
    utils.js
  tsconfig.json
  package.json

Los archivos fuente .ts residen en src/ y los archivos compilados .js se generan en dist/. Para compilar todo el proyecto:

npx tsc

Sin argumentos, tsc busca el tsconfig.json en el directorio actual y compila todos los archivos incluidos.

Modo watch y scripts de npm

Modo watch con tsc

El modo watch del compilador monitoriza los archivos fuente y recompila automáticamente cuando detecta cambios:

npx tsc --watch

El compilador permanece activo, mostrando mensajes cada vez que recompila. Esto es útil cuando se necesita el JavaScript generado (por ejemplo, para un proceso de Node.js que observa la carpeta dist/).

Scripts de npm

Definir scripts en package.json simplifica los comandos habituales del proyecto:

{
  "name": "mi-proyecto-ts",
  "versión": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "tsx": "^4.0.0"
  }
}

Los scripts cubren los flujos de trabajo principales:

• npm run build: compila el proyecto completo.
• npm run start: ejecuta el JavaScript compilado.
• npm run dev: ejecuta el proyecto con recarga automática durante el desarrollo.
• npm run typecheck: verifica los tipos sin generar archivos de salida.

npm run dev

El comando npm run dev inicia tsx en modo watch, que recompila y reejecuta el archivo de entrada cada vez que se modifica cualquier archivo del proyecto.

TypeScript Playground

El TypeScript Playground es un entorno en línea accesible en typescriptlang.org/play que permite escribir y probar código TypeScript sin instalar nada localmente.

El Playground ofrece varias funcionalidades útiles:

• Panel de JavaScript generado: muestra en tiempo real el JavaScript que resulta de compilar el código TypeScript escrito.
• Panel de errores: señala errores de tipos de forma inmediata.
• Configuración del compilador: permite modificar las opciones de compilación para observar como afectan al comportamiento.
• Compartir código: genera URLs únicas para compartir fragmentos de código con otras personas.

// Ejemplo para probar en el Playground
type Operación = (a: number, b: number) => number;

const sumar: Operación = (a, b) => a + b;
const restar: Operación = (a, b) => a - b;
const multiplicar: Operación = (a, b) => a * b;

function aplicarOperacion(operación: Operación, x: number, y: number): number {
  return operación(x, y);
}

console.log(aplicarOperacion(sumar, 10, 5));
console.log(aplicarOperacion(restar, 10, 5));
console.log(aplicarOperacion(multiplicar, 10, 5));

El Playground es especialmente útil para experimentar con configuraciones del compilador, probar patrones de tipos y compartir ejemplos reproducibles cuando se trabaja en equipo o se consulta documentación.