declare no TypeScript: para que serve e como usar

Por que o TypeScript precisa da palavra-chave declare?

Imagine que você está construindo uma casa, mas alguns cômodos já existem — foram construídos por outra pessoa (por exemplo, uma biblioteca JavaScript). Você não pode entrar lá e reformar as paredes, mas precisa conhecer a planta deles para posicionar os móveis corretamente. Esse é exatamente o papel da palavra-chave declare no TypeScript.

Se você já trabalhou com bibliotecas populares (jQuery, Lodash, D3.js), com certeza já se deparou com arquivos .d.ts — são essas "plantas" criadas com declare. Neste artigo, vamos entender o que é declare, para que serve e como usá-lo na prática. Prepare-se: vai ter bastante código e pouca enrolação.

O que é declare no TypeScript?

declare é uma palavra-chave que informa ao compilador TypeScript: "Ei, essa coisa (variável, função, classe ou módulo) existe, mas está definida em outro lugar. Apenas confie em mim e deixe eu usá-la no código."

É importante entender: declare não gera nenhum código JavaScript. É uma construção puramente informativa para o compilador. Se você escrever declare const x: number = 5, após a compilação o x desaparecerá — ele não estará no arquivo final.

Quando usar?

\n
• Trabalhando com variáveis globais — como window, document ou variáveis adicionadas via CDN.
\n
• Tipagem de bibliotecas JavaScript — quando a biblioteca é escrita em JS puro, mas você quer usá-la com TypeScript.
\n
• Criação de tipos para arquivos de configuração — módulos CSS, imagens, arquivos JSON.
\n

Sintaxe do declare: exemplos básicos

1. Declaração de variáveis

Suponha que você tenha uma variável global VERSION, definida no arquivo HTML via <script>. O TypeScript não sabe nada sobre ela, então você escreve:

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

Após a compilação, declare const VERSION: string desaparece, mas console.log(VERSION) permanece.

2. Declaração de funções

Imagine que você tem uma função global trackEvent de analytics:

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

O compilador não vai verificar a implementação — ele apenas conhece a assinatura.

3. Declaração de classes

Uma biblioteca fornece a classe Moment no espaço de nomes 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. Declaração de módulos

Este é o cenário mais comum. Por exemplo, módulos CSS ou arquivos 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

Agora você pode importar CSS e imagens sem erros no TypeScript.

declare e arquivos .d.ts

Arquivos com extensão .d.ts (declarações de tipos) são o "habitat natural" da palavra-chave declare. Eles contêm apenas declarações e não são compilados para JavaScript. Geralmente ficam na pasta types/ ou são fornecidos junto com a biblioteca (ex.: @types/lodash).

Exemplo: criando tipos para jQuery