Зачем нужно ключевое слово `declare` в TypeScript? Объясните на примерах

Главное отличие от обычного объявления (let, const, function) в том, что declare не создаёт никакого кода. Если вы напишете:

// Обычное объявление — TypeScript сгенерирует JS-код
var $: any; // В JS появится: var $;

// Объявление с declare — JS-код не генерируется
declare var $: any; // В JS ничего не добавится

Во втором случае вы просто описываете тип для уже существующего объекта (например, подключённого через CDN). Если бы вы использовали let $: any, TypeScript переопределил бы переменную, что может привести к конфликтам.

Где используется `declare`?

• Глобальные переменные (например, $ от jQuery, process от Node.js, __DEV__ от Webpack).
• Внешние библиотеки без типов — вы описываете их API вручную.
• Файлы деклараций (.d.ts) — основной способ описания типов для JS-библиотек.

Примеры использования

1. Глобальные переменные из CDN

// global.d.ts
declare var $: (selector: string) => JQuery;

// main.ts — теперь можно использовать $ без ошибок
$('.my-class').hide();

2. Описание модуля без типов

// lodash.d.ts
declare module 'lodash' {
  export function chunk(array: T[], size: number): T[][];
}

// app.ts
import { chunk } from 'lodash'; // Работает, хотя у lodash нет типов

3. Расширение существующих типов

// Добавляем свойство к глобальному window
declare global {
  interface Window {
    myCustomVar: string;
  }
}

// Теперь можно писать:
window.myCustomVar = 'hello';

Почему `.d.ts` файлы?

Файлы с расширением .d.ts — это "чистые" декларации. Они содержат только declare и не могут содержать реализаций. Это контракт: "Вот как выглядит API библиотеки, а реализация уже есть в JS". Обычные .ts файлы — это код, который компилируется. .d.ts — это только типы.

Итог: declare — это мост между миром JavaScript (где типов нет) и TypeScript (где типы обязательны). Он позволяет использовать существующий JS-код с полной проверкой типов, не генерируя лишнего кода.

// utils.ts (это модуль)
export function doSomething() {
  // Ошибка! $ не определена в этом контексте
  // $('div').hide();

  // Правильно: расширяем глобальный скоуп
  declare global {
    var $: (selector: string) => any;
  }
  // Теперь $ доступна
  $('div').hide();
}

declare namespace MyLib {
  function init(): void;
  interface Config {
    debug: boolean;
  }
}