declare en TypeScript: Para qué sirve y cómo usarlo

¿Para qué TypeScript necesita la palabra clave declare?

Imagina que estás construyendo una casa, pero algunas habitaciones ya existen — las construyó alguien más (por ejemplo, una librería JavaScript). No puedes entrar y rehacer las paredes, pero necesitas conocer su plano para colocar los muebles correctamente. Ese es exactamente el papel que cumple la palabra clave declare en TypeScript.

Si alguna vez has trabajado con librerías populares (jQuery, Lodash, D3.js), seguramente te has topado con archivos .d.ts — esos son los "planos" creados con declare. En este artículo analizaremos qué es declare, para qué sirve y cómo usarlo en la práctica. Prepárate — habrá mucho código y poca teoría.

¿Qué es declare en TypeScript?

declare es una palabra clave que le indica al compilador de TypeScript: "Oye, esto (variable, función, clase o módulo) existe, pero está definido en otro lugar. Solo confía en mí y permite usarlo en el código."

Es importante entender: declare no genera ningún código JavaScript. Es una construcción puramente informativa para el compilador. Si escribes declare const x: number = 5, después de la compilación x desaparecerá — no estará en el archivo final.

¿Cuándo se necesita?

\n
• Trabajar con variables globales — por ejemplo, window, document o variables añadidas mediante CDN.
\n
• Tipificar librerías JavaScript — cuando la librería está escrita en JS puro, pero quieres usarla con TypeScript.
\n
• Crear tipos para archivos de configuración — módulos CSS, imágenes, archivos JSON.
\n

Sintaxis de declare: ejemplos básicos

1. Declaración de variables

Supongamos que tienes una variable global VERSION, definida en un archivo HTML mediante <script>. TypeScript no sabe nada de ella, así que escribes:

declare const VERSION: string;\n\nconsole.log(VERSION); // OK, TypeScript sabe que es un string\n

Después de la compilación, declare const VERSION: string desaparecerá, pero console.log(VERSION) permanecerá.

2. Declaración de funciones

Imagina que tienes una función global trackEvent de analítica:

declare function trackEvent(eventName: string, properties?: Record<string, any>): void;\n\n// Uso\ntrackEvent("button_click", { buttonId: "submit" });\n

El compilador no verificará la implementación — solo conoce la firma.

3. Declaración de clases

Una librería proporciona la clase Moment desde el espacio de nombres global:

declare class Moment {\n    constructor(date: string);\n    format(pattern: string): string;\n}\n\n// Uso\nconst now = new Moment("2024-01-01");\nconsole.log(now.format("YYYY-MM-DD"));\n

4. Declaración de módulos

Este es el escenario más común. Por ejemplo, tienes módulos CSS o archivos JSON:

// styles.d.ts\ndeclare module "*.css" {\n    const styles: Record<string, string>;\n    export default styles;\n}\n\n// images.d.ts\ndeclare module "*.png" {\n    const src: string;\n    export default src;\n}\n

Ahora puedes importar CSS e imágenes sin errores de TypeScript.

declare y archivos .d.ts

Los archivos con extensión .d.ts (declaraciones de tipos) son el "hábitat natural" de la palabra clave declare. Contienen solo declaraciones y no se compilan a JavaScript. Generalmente se encuentran en la carpeta types/ o se incluyen con la librería (por ejemplo, @types/lodash).

Ejemplo: creando tipos para jQuery