TypeScript

Что такое TypeScript и JavaScript

JavaScript — язык программирования в браузере и в Node.js. В "Вселенной IT" на нём написаны React-компоненты, конфиги Docusaurus, remark-плагины и ESM-скрипты в scripts/. Подробнее — основы JavaScript и экосистема JS.

TypeScript — надстройка над JavaScript со статической типизацией. Компилятор tsc и TS server проверяют совместимость данных до запуска в браузере, IDE подсказывает поля и сигнатуры. TypeScript стирается при сборке — в продакшен-бандл попадает обычный JS. Обзор в энциклопедии — TypeScript в курсе JS, углублённо — типы и типизация.

В it-knowledge-base большая часть UI остаётся на JSX, TypeScript подключён для типобезопасности в swizzle-теме, утилитах дизайна и постепенной миграции. Сборку ведёт Docusaurus (Babel/SWC через Webpack или Rspack), отдельный tsc --emit для деплоя не нужен.

---

Как настраивается TypeScript в проекте

Точка входа — tsconfig.json в корне репозитория. Файл говорит компилятору, какие файлы анализировать, какие версии JS и DOM считать доступными, как обрабатывать JSX и модули.

Дополнительные слои типов.

Файл	Роль
tsconfig.json	Основные compilerOptions
src/types.d.ts	Ссылки на типы Docusaurus (@docusaurus/module-type-aliases)
src/docusaurus-shims.d.ts	Заглушки для @theme/*, html2canvas, jspdf
package.json → devDependencies	typescript, @types/react, @types/node

Запуск проверки вручную (в IDE TS server делает это постоянно).

npx tsc --noEmit

Официальная npm run build не вызывает tsc — падение сборки из-за типов возможно только после добавления шага CI с tsc --noEmit.

---

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "allowJs": true,
    "checkJs": false,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "skipLibCheck": true,
    "strict": false,
    "types": ["node", "@docusaurus/module-type-aliases"]
  },
  "include": ["src/**/*", "docusaurus.config.js", "sidebars.js"]
}

Справочник по полям в энциклопедии — tsconfig в справочнике 301, форматы и подключение TS.

---

compilerOptions — разбор

Опция	Значение	Практический смысл
target	ES2020	Версия JS, на которую ориентируется проверка (реальную транспиляцию делает Babel/SWC)
lib	DOM, DOM.Iterable, ES2020	Какие встроенные API TypeScript "знает" — document, fetch, итераторы
module	ESNext	Синтаксис ESM import/export
moduleResolution	Bundler	Разрешение импортов как у Vite/Webpack — без расширений .js
jsx	react-jsx	JSX runtime React 17+ — import React в каждом TSX необязателен
allowJs	true	Рядом с .ts/.tsx можно держать .js/.jsx
checkJs	false	JS-файлы в анализ типов не входят
resolveJsonModule	true	import data from './file.json' с типами
isolatedModules	true	Каждый файл — отдельный модуль для Babel/SWC (без const enum и т.п.)
noEmit	true	tsc не пишет .js на диск — только проверка и подсказки
skipLibCheck	true	Не проверять .d.ts в node_modules — быстрее
strict	false	Мягкий режим — меньше трения при миграции
types	node, @docusaurus/module-type-aliases	Подключаемые глобальные пакеты типов

lib и библиотеки

lib в compilerOptions — список встроенных определений TypeScript (DOM, ES2020…). Это отдельный слой от npm-пакетов; он описывает window, Promise, Map и т.д.

Библиотеки в смысле npm — @types/react, @types/node из devDependencies. Поле types ограничивает, какие @types/* подтягиваются автоматически; остальные подключаются через import или /// <reference types="..." />.

isolatedModules и модули

isolatedModules: true согласует TypeScript с Babel/SWC, которые транспилируют файл за файлом, без полного графа проекта. Запрещает конструкции, требующие анализа всего проекта (например, const enum без preserveConstEnums).

Модули в src/ — в основном ESM (import/export). Исключение — осознанный require в swizzle-TSX для части @theme/* (компромисс ниже).

strict и types

strict: false — strictNullChecks, noImplicitAny и другие флаги строгости выключены. Типобезопасность есть там, где явно описаны interface и type; остальной код мигрирует постепенно. Цель — включить strict: true, когда ядро swizzle-темы без слабых any.

types — белый список глобальных деклараций. @docusaurus/module-type-aliases даёт типы для алиасов @site, @theme, @generated.

include

"include": ["src/**/*", "docusaurus.config.js", "sidebars.js"]

Проверяются исходники src/, корневой конфиг и sidebars.js. Папка docs/ вне include — статьи типизируются через MDX без TS-компиляции отдельно от Docusaurus.

noEmit и tsc --emit

Режим	Команда	Результат
Проверка без вывода	tsc --noEmit	Только диагностика; совпадает с noEmit: true в config
Эмит JS на диск	tsc (без noEmit)	Папка с .js — в проекте не используется для сайта
Сборка сайта	npm run build	Docusaurus + Webpack, TypeScript стирается Babel/SWC

tsc --emit в быту — любой запуск компилятора с записью файлов. В it-knowledge-base включён noEmit — TypeScript только для IDE, CI и рефакторинга; артефакты сборки создаёт Docusaurus.

---

Babel, SWC и сборка

Docusaurus 3 транспилирует .ts/.tsx/.jsx через цепочку сборщика (Webpack/Rspack), без отдельного шага tsc --emit.

Слой	Роль
Webpack / Rspack	Граф зависимостей, чанки, бандл
Babel (по умолчанию)	JSX → JS, современный синтаксис → целевой браузер
SWC через @docusaurus/faster	Ускоренная транспиляция при future.experimental_faster

TypeScript здесь — исходный формат; типы удаляются при транспиляции. См. архитектура компиляции TS.

---

Форматы .ts / .tsx и JSX

Расширение	Содержимое	Где в проекте
.js / .jsx	JavaScript + JSX	~49 компонентов в src/components/, remark, clientModules
.ts	Логика без разметки	itDesignTheme.ts, articleMetaEnhancement.ts, тесты
.tsx	TypeScript + JSX	src/theme/**, DesignThemePicker

JSX

JSX — синтаксис разметки внутри JavaScript (<div>, <ArticlePdfExport />). Сборщик превращает его в вызовы React.createElement или в automatic JSX runtime. Учебник — React, компоненты и JSX.

JSX runtime

Опция "jsx": "react-jsx" включает новый JSX transform (React 17+). Компилятор сам подключает функции из react/jsx-runtime, поэтому в TSX часто достаточно import {type ReactNode} from 'react' без import React.

---

Алиасы путей

Docusaurus и Webpack задают виртуальные префиксы; типы — в @docusaurus/module-type-aliases и docusaurus-shims.d.ts.

Импорт	Разрешается в
@site/src/components/Foo	src/components/Foo
@theme/DocItem/Layout	src/theme/DocItem/Layout или оригинал из node_modules
@theme-original/*	Несвиззленный компонент темы
@generated/...	Артефакты сборки Docusaurus (маршруты, registry)

Пример из swizzle-темы.

import lazyDemo from '@site/src/components/shared/lazyDemo';
import {useDoc} from '@docusaurus/plugin-content-docs/client';
import type {Props} from '@theme/Navbar/ColorModeToggle';

Алиас (@site, @theme) — короткий стабильный путь вместо длинных относительных ../../../. IDE и tsc понимают их через пакет типов Docusaurus.

Vite / Webpack

Webpack — сборщик Docusaurus по умолчанию (статья про экосистему JS). Vite — альтернативный dev/build-инструмент в других стеках; опция moduleResolution: "Bundler" в tsconfig отражает правила таких сборщиков (импорт без .ts в пути). В проекте с IT_DOCUSAURUS_FASTER=1 часть пайплайна уходит на Rspack + SWC.

Артефакты сборки

Папка build/ после npm run build — HTML, JS, CSS для продакшена. Промежуточно Docusaurus пишет в .docusaurus/ — сгенерированные маршруты, registry компонентов; префикс @generated/ в импортах указывает на эти файлы. Это артефакты плагинов Docusaurus, отдельно от вывода tsc.

---

Где уже TypeScript

Область	Файлы	Зачем TS
src/theme/	~19 .tsx	Swizzle layout, navbar, sidebar, DocSearch
src/utils/	itDesignTheme.ts	Дизайн-темы, типы из JSON
src/components/	DesignThemePicker/index.tsx	UI выбора дизайна с типами
src/theme/DocItem/Layout/	articleMetaEnhancement.ts, articleSectionEnhancement.ts	DOM-утилиты статьи
Тесты	articleSectionEnhancement.test.ts	Логика без полного E2E

Остальные ~49 компонентов в src/components/ — .jsx / .js. Статьи в docs/ — MDX без TS.

Типизированная утилита дизайна

// src/utils/itDesignTheme.ts
export type ItDesignMode = 'light' | 'dark';

export interface ItDesign {
  id: string;
  name: string;
  mode: ItDesignMode;
  featured?: boolean;  // опциональность
}

export function applyItDesign(designId: string): ItDesign {
  // ...
}

itDesigns.json импортируется благодаря resolveJsonModule: true; литерал as ItDesign[] связывает JSON с интерфейсом.

---

docusaurus-shims.d.ts

Файл src/docusaurus-shims.d.ts объявляет модули без готовых @types/*.

• @theme/*, @theme-original/* — fallback ComponentType<any> и Props
• html2canvas, jspdf — минимальные сигнатуры для PDF
• глобальный namespace JSX — запасной вариант для сред без @types/react

При новой JS-библиотеке без типов — declare module 'имя-пакета' или установка @types/имя-пакета.

src/types.d.ts.

/// <reference types="@docusaurus/module-type-aliases" />
/// <reference types="@docusaurus/plugin-content-docs/client" />

Подключает типы алиасов и клиента docs (в т.ч. useDoc).

---

Swizzle-тема и props

Команда swizzle копирует компоненты @docusaurus/theme-classic в src/theme/. В проекте swizzle уже выполнен; новые правки — в .tsx с явными props.

import type {Props} from '@theme/Navbar/ColorModeToggle';

export default function NavbarColorModeToggle({className}: Props): ReactNode {
  // ...
}

Props — контракт входных данных компонента. type Props из @theme/... наследует оригинальную сигнатуру темы — при обновлении Docusaurus расхождения видны в IDE.

CJS-компоненты и require

В DocItem/Layout/index.tsx часть модулей темы подключают через require — компромисс между ESM-синтаксисом файла и тем, как Docusaurus резолвит некоторые @theme/* в runtime.

// eslint-disable-next-line @typescript-eslint/no-require-imports
const DocItemContent = require('@theme/DocItem/Content').default;

CommonJS (require) и ESM (import) сосуществуют в одном TSX; для типов можно использовать typeof import('@theme/DocItem/Content').default.

---

lazyDemo и ленивая загрузка

src/components/shared/lazyDemo.js — обёртка над React.lazy + Suspense для тяжёлых блоков (PDF, блок "См. также", hero).

export default function lazyDemo(importFn) {
  const LazyComponent = lazy(importFn);
  return function LazyDemo(props) {
    return (
      <Suspense fallback={demoSkeletonFallback()}>
        <LazyComponent {...props} />
      </Suspense>
    );
  };
}

В TSX layout.

const TechArticleHero = lazyDemo(
  () => import('@site/src/components/TechArticleHero'),
);
const ArticlePdfExport = lazyDemo(() => import('@site/src/components/ArticlePdfExport'));

Ленивая загрузка — отдельный async-чанк подгружается при первом рендере компонента, отдельно от главного бандла. См. lazy-import в конфиге.

---

useDoc

useDoc — React-хук из @docusaurus/plugin-content-docs/client. Возвращает метаданные текущей статьи — metadata, frontMatter, toc.

function useDocTOC() {
  const {frontMatter, toc} = useDoc();
  const hidden = frontMatter.hide_table_of_contents;
  const canRender = !hidden && toc.length > 0;
  // ...
}

Используется в DocItem/Layout/index.tsx, TechArticleHero.jsx, ArticleRelated.jsx. В TSX поля frontMatter частично типизированы через пакет плагина docs; кастомные поля (теги, slug) остаются расширяемыми.

---

MDX и TypeScript

Статьи в docs/ пишутся без TS. Типизация MDX-компонентов опциональна.

1. JSDoc в .jsx (быстрый путь).

/**
 * @param {{ example?: string, title: string, minHeight?: number }} props
 */
function ExternalPlayEmbedInner({example, title, minHeight = 320}) {

2. Переписать компонент в .tsx и импортировать из MDX как раньше.

3. Оставить JSX — достаточно для стабильного API компонентов.

---

Стратегия миграции

1. Новый код в src/theme/ — сразу .tsx (layout, navbar, sidebar — максимум пользы от типов).
2. Компоненты статей — .jsx, пока API стабилен; TS при крупном рефакторинге.
3. strict: true — когда swizzle-ядро без слабых any.
4. Тесты — .test.ts рядом с enhancement-модулями (логика DOM без полного Docusaurus).
5. remark / scripts — остаются .js / .mjs; типы через JSDoc или постепенный .ts.

---

TS server

TypeScript Server (tsserver) — фоновый процесс IDE (VS Code, Cursor). Читает tsconfig.json, строит граф проекта, отдаёт автодополнение, переход к определению и подсветку ошибок. Подробнее — статья TS Server.

Если после смены алиасов импорт @site/... подсвечивается как ошибка — перезапустить TS server (Command Palette → "TypeScript: Restart TS Server").

---

Частые проблемы

Симптом	Решение
Cannot find module @site/...	Проверить путь; перезапустить TS server
ReactNode vs JSX.Element	Для children предпочитать ReactNode
Ошибка импорта JSON	resolveJsonModule: true уже в config
require в TSX	eslint-disable или тип через typeof import
Типы @theme/Props = any	Уточнить swizzle или дописать shim

---

Глоссарий

TypeScript

Язык с надстройкой типов над JavaScript; в проекте — проверка и IDE, сборка через Docusaurus.

JavaScript

Базовый язык runtime; JSX-компоненты, конфиги, remark, большинство src/components/.

JSX

Синтаксис UI в .js/.jsx/.tsx; компилируется в вызовы React. См. React и JSX.

Типобезопасность

Свойство кода, при котором несовместимые операции отлавливаются до выполнения (статическая проверка). В TS — через типизацию и strict.

Swizzle-тема

Кастомные копии компонентов @docusaurus/theme-classic в src/theme/, преимущественно .tsx.

Утилита

Вспомогательный модуль без UI — itDesignTheme.ts, articleMetaEnhancement.ts, lazyDemo.js.

Дизайн

Визуальные темы оформления (data-design, itDesigns.json); типы в ItDesign, UI в DesignThemePicker.

Миграция

Постепенный перевод .jsx → .tsx и ужесточение strict.

Сборка

npm run build → Docusaurus → Webpack/Rspack → build/. Отдельный emit tsc не используется.

Babel/SWC

Транспиляторы JS/TS/JSX в бандл; типы стираются.

tsconfig.json

Конфиг компилятора TypeScript — compilerOptions, include.

compilerOptions

Секция настроек внутри tsconfig.json.

lib

Список встроенных API (DOM, ES2020) для проверки типов.

isolatedModules

Режим "один файл — один модуль" для совместимости с Babel/SWC.

strict

Набор строгих проверок TypeScript; в проекте false на время миграции.

types

Поле compilerOptions.types — какие @types пакеты видны глобально.

include

Маска файлов проекта для tsc и TS server.

JSX runtime

Automatic transform React 17+; включается "jsx": "react-jsx".

Vite/Webpack

Сборщики модулей; Docusaurus использует Webpack/Rspack, moduleResolution: "Bundler" отражает их правила.

Алиасы

Префиксы @site, @theme, @generated вместо относительных путей.

Артефакты сборки

build/, .docusaurus/, @generated/* — выход Docusaurus, не tsc.

lazyDemo

Хелпер React.lazy + Suspense для отложенной загрузки тяжёлых компонентов.

Ленивая загрузка

Загрузка JS-чанка по требованию при первом показе компонента.

useDoc

Хук Docusaurus — метаданные и toc текущего документа.

Типизация

Процесс и результат описания типов данных в коде. См. типизация в TS.

Типизированные утилиты

Функции и интерфейсы в .ts с явными сигнатурами (ItDesign, applyItDesign).

Правка

Изменение swizzle-файлов в src/theme/ — предпочтительно в .tsx с типами props.

props

Входные параметры React-компонента; в swizzle часто type Props из @theme/....

CJS-компоненты

Модули CommonJS, подключаемые через require().default в TSX.

require

Функция CommonJS для загрузки модуля; компромисс в layout.

Компромисс

Осознанное смешение import и require ради совместимости с резолвом темы Docusaurus.

Опциональность

Поле с ? в interface (featured?: boolean) — может отсутствовать.

TS server

tsserver в IDE — автодополнение, диагностика, навигация по типам.

noEmit

tsc не записывает .js; только проверка типов.

tsc --emit

Запуск компилятора с выводом JS-файлов; в проекте не применяется для сайта.

Проверка типов

npx tsc --noEmit или диагностика TS server. См. package.json и стек.

---

Связь с другими главами

• package.json и стек — typescript, @types/*, SWC, сборка.
• docusaurus.config.js — Webpack, faster, lazy-import.
• Структура src/ — папки theme/, components/, utils/.
• Компоненты — JSDoc, MDX, embed.

Полезные статьи энциклопедии

• TypeScript — обзор в курсе JS
• Типы данных и типизация в TypeScript
• Экосистема и архитектура TypeScript
• Форматы и подключение TypeScript
• Архитектура компиляции TS
• TypeScript Server
• Справочник tsconfig (301)
• JavaScript — модули import/export
• React — компоненты, JSX
• Типы данных в вычислительных системах
• Webpack и экосистема JS