Как подключить TypeScript к HTML

Короткий ответ: TypeScript нельзя подключить к HTML как обычный JavaScript-файл. Браузер не выполняет .ts напрямую. Нужно написать код в app.ts, скомпилировать его в app.js, а уже готовый JavaScript подключить в HTML через <script src="app.js" defer></script>

Минимальная схема такая:

src/app.ts      -> TypeScript-код
public/app.js   -> результат компиляции
public/index.html -> подключает app.js

Содержание

Подготовьте проект
Настройте компиляцию
Подключите JavaScript в HTML
Как быстро проверить через локальный сервер
Почему не работает script с .ts
Самопроверка
Частые ошибки
Что почитать дальше по TypeScript

Подготовьте проект

Создайте папку и установите TypeScript:

mkdir ts-html-demo
cd ts-html-demo
npm init -y
npm install typescript --save-dev

Создайте структуру:

ts-html-demo/
  public/
    index.html
  src/
    app.ts
  package.json

В src/app.ts добавьте простой код:

const title: string = "TypeScript подключен к HTML";

const heading = document.querySelector<HTMLHeadingElement>("#title");

if (heading) {
  heading.textContent = title;
}

Здесь TypeScript помогает уточнить тип элемента: HTMLHeadingElement. Если элемент найден, мы меняем текст заголовка на странице

Настройте компиляцию

Создайте tsconfig.json:

npx tsc --init

Для учебного примера можно оставить настройки так:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "strict": true,
    "outDir": "public"
  },
  "include": ["src"]
}

Теперь команда npx tsc возьмет TypeScript из папки src и положит JavaScript в public

Скомпилируйте проект:

npx tsc

После этого должен появиться файл public/app.js

Подключите JavaScript в HTML

Создайте public/index.html:

<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>TypeScript и HTML</title>
    <script src="./app.js" defer></script>
  </head>
  <body>
    <h1 id="title">Загрузка...</h1>
  </body>
</html>

Атрибут defer нужен, чтобы скрипт выполнился после разбора HTML. Тогда document.querySelector("#title") найдет элемент, а не вернет null из-за слишком раннего запуска

Откройте public/index.html в браузере. Если все сделано правильно, вместо Загрузка... появится текст TypeScript подключен к HTML

Как быстро проверить через локальный сервер

Для простого примера можно открыть HTML-файл напрямую. Но если дальше появятся модули, импорты или запросы к файлам, лучше запустить локальный сервер:

npx serve public

Если serve не установлен, npm предложит временно скачать пакет. После запуска откройте адрес, который появится в терминале

Почему не работает script с .ts

Новички часто пробуют так:

<script src="./app.ts"></script>

Это ошибка. Браузер понимает JavaScript, но не понимает TypeScript-синтаксис: аннотации типов, интерфейсы, дженерики и часть настроек модулей. TypeScript нужен на этапе разработки. На страницу попадает результат компиляции

Еще одна частая ошибка — подключить app.js, но забыть выполнить npx tsc. В этом случае HTML смотрит на файл, которого еще нет, или на старую версию файла

Самопроверка

Поменяйте строку:

const title: string = "TypeScript подключен к HTML";

на:

const title: string = "Проверка прошла";

Затем снова выполните:

npx tsc

Обновите страницу в браузере. Если текст изменился, цепочка работает: .ts -> компиляция -> .js -> HTML

Частые ошибки

Если в браузере ничего не меняется, откройте DevTools и посмотрите вкладку Console. Ошибка Failed to load resource обычно значит, что путь в src="./app.js" не совпадает с реальным расположением файла

Если TypeScript ругается на document, проверьте, что в tsconfig.json не отключены DOM-типы. Для браузерного проекта в lib должен быть DOM, либо поле lib можно не указывать и оставить стандартные настройки

Если querySelector возвращает null, проверьте id в HTML и селектор в TypeScript. Также оставьте defer, чтобы код не выполнялся до появления HTML-элемента

Что почитать дальше по TypeScript

Если нужен общий маршрут по теме, откройте рубрику TypeScript. Для соседних задач пригодятся эти разборы: