Instalar TypeScript con npm y comprobar la versión

TypeScript es un paquete de npm llamado typescript. Instálalo en tu proyecto y comprueba que funciona:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

El paquete incluye el comando tsc, el compilador de TypeScript. Para instalarlo necesitas Node.js y npm (que viene con Node.js); descarga Node.js de nodejs.org o del gestor de paquetes de tu sistema y compruébalo con node --version.

No necesitas instalar nada para probar TypeScript. Este bloque se compila y se ejecuta en tu navegador:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

Instalar TypeScript en un proyecto

La instalación recomendada es local, como dependencia de desarrollo del proyecto:

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript (forma corta npm i -D typescript) pone el compilador en node_modules y lo registra en package.json:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

Es una dependencia de desarrollo porque solo hace falta para compilar el código, no para ejecutarlo. Cualquiera que clone el proyecto y ejecute npm install obtiene la misma versión del compilador.

Para ejecutar el compilador local, ponle delante npx, que busca los comandos en node_modules/.bin:

npx tsc --version

Dentro de los scripts de package.json puedes escribir tsc sin npx, porque npm añade node_modules/.bin al PATH de los scripts:

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

Así npm run build compila y npm run typecheck comprueba los tipos sin escribir ningún archivo.

Comprobar la versión de TypeScript

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

Si npx tsc --version y tsc --version imprimen versiones distintas, el proyecto tiene su propio compilador y el global es más antiguo o más nuevo. La versión del proyecto es la que cuenta para su build.

Instalar TypeScript de forma global

Una instalación global te da un comando tsc en cualquier terminal, sin npx:

npm install -g typescript
tsc --version

En macOS y Linux esto puede fallar con errores de permisos EACCES cuando Node.js se instaló para todo el sistema. Instalar Node.js con un gestor de versiones como nvm o fnm lo evita, y no se recomienda usar sudo npm install -g.

Usa el comando global para pruebas rápidas. En un proyecto real, mantén también una instalación local: así package.json registra la versión y una actualización del compilador global no puede cambiar cómo se compila el proyecto.

Instalar con pnpm, Yarn o Bun

Todos los gestores de paquetes de JavaScript instalan el mismo paquete:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

Ejecuta el compilador con pnpm tsc, yarn tsc o bunx tsc.

Crear un tsconfig.json con tsc --init

Un archivo tsconfig.json marca una carpeta como proyecto TypeScript y guarda las opciones del compilador. Genera uno:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

El archivo generado (TypeScript 7) activa strict y algunas comprobaciones más, usa "module": "nodenext" y "target": "esnext", y tiene líneas comentadas para rootDir y outDir. Descomenta esas dos para que el compilador lea de src y escriba en dist:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

Es una vista abreviada; el archivo real tiene más opciones, cada una con un comentario. La página de tsconfig explica qué hacen. Si vuelves a ejecutar npx tsc --init en la misma carpeta, falla con error TS5054: A 'tsconfig.json' file is already defined, así que nunca sobrescribe tu configuración.

Compilar tu primer archivo

Crea src/index.ts:

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

Después compila y ejecuta:

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

npx tsc sin argumentos lee tsconfig.json, comprueba los tipos de todos los archivos que incluye y escribe la salida en dist. Con la configuración generada obtienes index.js más index.d.ts (declaraciones de tipos) y archivos .map (source maps) para cada uno.

Dos cosas que conviene saber sobre la salida:

• Por defecto, los errores de tipo no detienen la salida. tsc informa de los errores, termina con un código distinto de cero y aun así escribe el JavaScript. Pon "noEmitOnError": true para no escribir nada mientras haya errores.
• Si hay un tsconfig.json, no pases nombres de archivo. npx tsc src/index.ts falla con error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Ejecuta npx tsc sin más, o añade --ignoreConfig si de verdad quieres compilar un archivo con la configuración por defecto.

Modo watch

--watch (forma corta -w) mantiene el compilador en marcha y recompila cada vez que cambia un archivo:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

Déjalo abierto en una terminal junto al editor. Detenlo con Ctrl+C.

Instalar una versión concreta de TypeScript

Añade la versión después de @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 es la última versión cuyo compilador está escrito en JavaScript. Algunas herramientas que llaman a la API JavaScript del compilador aún la necesitan; la página de TypeScript 7 lo explica, junto con cómo actualizar.

Configurar el editor

VS Code trae soporte para TypeScript integrado: abre un archivo .ts y tienes subrayado de errores, autocompletado, tipos al pasar el ratón y renombrado sin instalar nada. Para tener la velocidad de TypeScript 7 en el editor, el equipo de TypeScript publica una extensión que cambia VS Code al servidor de lenguaje nativo de TypeScript 7. WebStorm y los demás IDE de JetBrains admiten TypeScript de serie, y Neovim, Vim, Emacs, Zed y Sublime Text usan un servidor de lenguaje de TypeScript a través de su soporte LSP.

Errores comunes al instalar

This is not the tsc command you are looking for. Ejecutaste npx tsc en una carpeta sin TypeScript instalado, y npx descargó un paquete obsoleto que casualmente se llama tsc. Instala el de verdad con npm install --save-dev typescript.

tsc: command not found, o 'tsc' is not recognized as an internal or external command en Windows. TypeScript no está instalado de forma global, o la carpeta global de npm no está en tu PATH. Usa npx tsc en un proyecto con instalación local, o instálalo de forma global y abre una terminal nueva.

error TS2591: Cannot find name 'process' (o require; __dirname da TS2304). Las APIs propias de Node.js tienen sus tipos en un paquete aparte. Instálalo con npm install --save-dev @types/node y añade "types": ["node"] a compilerOptions: TypeScript 7 ya no carga automáticamente todos los paquetes @types instalados.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Tus archivos están en src y fijaste outDir pero no rootDir. Añade "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y escribe "type": "commonjs" en package.json, así que la configuración de tsc --init ("module": "nodenext" con verbatimModuleSyntax) trata cada archivo .ts como CommonJS, donde import y export no están permitidos. Cámbialo a "type": "module" y escribe los imports relativos con extensión .js: import { add } from "./math.js".