Що таке triple-slash директиви і коли вони ще потрібні?

Triple-slash директиви - коментарі з трьома скісними рисками й XML-тегом, які TypeScript читає як інструкції компілятору:

/// <reference types="vite/client" />
/// <reference path="./legacy-globals.d.ts" />
/// <reference lib="es2025.collection" />

Види:

• types="..." - підключити декларації пакета (як елемент масиву types у tsconfig, але для конкретного файлу);
• path="..." - включити інший файл у компіляцію;
• lib="..." - підключити вбудовану бібліотеку типів (наприклад, нові можливості ECMAScript) без зміни lib у tsconfig.

Головне правило - лише на початку файлу. Директива діє, тільки якщо перед нею немає нічого, крім коментарів і інших директив. Після першого виразу чи імпорту це звичайний коментар - без попереджень:

import { a } from './a.js';
/// <reference types="node" />   // ігнорується мовчки

Де вони ще доречні:

• vite-env.d.ts у проєктах Vite - /// <reference types="vite/client" />: підключає типи import.meta.env і імпорту ресурсів;
• файли .d.ts, що публікуються в пакеті, - щоб декларації явно залежали від іншого пакета типів (/// <reference types="node" />), коли без глобальних типів Node.js вони не мають сенсу;
• окремі файли з особливими потребами - тестовий файл, якому потрібні глобальні типи фреймворку, коли решті проєкту вони не потрібні.

Де вони застаріли:

• path для зв'язку модулів - ES-імпорти роблять це природно; path лишився для старого коду без модулів;
• /// <reference no-default-lib="true"/> у TypeScript 6 перестала підтримуватися (замість неї - noLib чи libReplacement);
• /// <amd-module /> втратила сенс разом із видаленням module: amd у TypeScript 6/7.

Порівняно з tsconfig: налаштування в tsconfig.json (types, lib, include) діють на весь проєкт і видні одразу. Директиви «ховають» залежності в окремих файлах. Тому в застосунках перевага за tsconfig, а директиви - для .d.ts і особливих файлів.

Пов'язана зміна TypeScript 6/7: через порожній за замовчуванням types директива /// <reference types="..." /> знову стала корисним способом підключити глобальні типи для окремого файлу.

Докладніше в документації: Triple-slash директиви