Anotaciones de tipos JSDoc como puente
Añada tipos a archivos JS mediante JSDoc antes de convertirlos.
Anotaciones de tipos JSDoc como puente es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 4 lecciones en total.
JSDoc como puente hacia TypeScript
TypeScript puede leer las anotaciones de tipos JSDoc en archivos JavaScript cuando checkJs: true está habilitado. Esto permite añadir tipos al código JS sin cambiar el nombre de los archivos.
/** @type {string} */
let name = "Alice"; // TypeScript checks this as string@param y @returns
Anote los parámetros de las funciones y sus tipos de retorno mediante etiquetas JSDoc.
/**
* @param {string} name
* @param {number} age
* @returns {string}
*/
function greet(name, age) {
return `${name} is ${age}`;
}@typedef para tipos de objetos
Utilice @typedef para definir alias de tipos reutilizables en JSDoc.
/**
* @typedef {Object} User
* @property {string} id
* @property {string} name
* @property {boolean} isActive
*/
/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };@template para genéricos
Utilice @template para escribir funciones genéricas en JSDoc.
/**
* @template T
* @param {T[]} arr
* @returns {T | undefined}
*/
function first(arr) {
return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefinedImportar tipos desde archivos .ts
JSDoc admite @type {import("./types").User} para importar tipos de TypeScript en archivos JS.
/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };@ts-check para la comprobación por archivo
Añada // @ts-check al principio de un archivo JS para habilitar la comprobación de TypeScript únicamente en ese archivo, sin establecer checkJs: true de forma global.
// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number@ts-ignore y @ts-expect-error
Suprima errores específicos de tipos JSDoc con directivas insertadas en el código, sin deshabilitar el archivo completo.
// @ts-ignore
const x = badFunction(); // single error suppressed
// @ts-expect-error
const y = anotherBad(); // error expected hereEnumeraciones JSDoc
Simule enumeraciones de TypeScript en JSDoc mediante @enum.
/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };Aserciones de tipos en JSDoc
Utilice /** @type {SomeType} */ (expression) para realizar aserciones de tipos JSDoc, lo que equivale a as SomeType de TypeScript.
const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typedCuándo pasar a .ts
Las anotaciones JSDoc son un puente, no el destino final. Cuando un archivo esté completamente anotado y sea estable, cámbiele el nombre a .ts y elimine los comentarios de tipos JSDoc en favor de la sintaxis nativa de TypeScript.
// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)Resumen: JSDoc como puente
Las anotaciones de tipos JSDoc habilitan la comprobación de TypeScript en archivos JS sin cambiarles el nombre. Utilice @type, @param, @typedef y @template para añadir seguridad de tipos de forma incremental antes de convertirlos a TypeScript nativo.
Comprobación rápida
¿Qué etiqueta JSDoc habilita la comprobación de TypeScript en un solo archivo sin activar globalmente checkJs?
Lo que ha aprendido
Las anotaciones de tipos JSDoc sirven de puente entre JavaScript y TypeScript: utilice @type, @param, @typedef y @template para añadir tipos a los archivos JS. Habilite la comprobación por archivo con // @ts-check y, cuando esté listo, convierta el archivo a TypeScript nativo.
Preguntas frecuentes
¿La lección «Anotaciones de tipos JSDoc como puente» es gratis?
Sí — el texto completo de «Anotaciones de tipos JSDoc como puente» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Anotaciones de tipos JSDoc como puente»?
Añada tipos a archivos JS mediante JSDoc antes de convertirlos. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar TypeScript Academy?
No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.
¿Cuánto tiempo toma la lección «Anotaciones de tipos JSDoc como puente»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?
Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Inicio de la migración: allowJs y checkJs
- Anotaciones de tipos JSDoc como puente
- Estrategia de conversión archivo por archivo
- Cómo trabajar con bibliotecas de terceros sin tipos