Начало работы с TypeScript

Установка

Visual Studio Code предоставляет отличную поддержку языка TypeScript, но не включает компилятор TypeScript. Чтобы установить компилятор TypeScript, можно воспользоваться менеджером пакетов, например npm или yarn:

npm install typescript --save-dev

или

yarn add typescript --dev

Обязательно зафиксируйте созданный lock-файл в репозитории, чтобы все участники команды использовали одну и ту же версию TypeScript.

Для запуска компилятора TypeScript можно использовать следующие команды:

npx tsc

или

yarn tsc

Рекомендуется устанавливать TypeScript локально для каждого проекта, а не глобально, поскольку это делает процесс сборки более предсказуемым. Однако для разовых задач можно использовать следующую команду:

npx tsc

или установить его глобально:

npm install -g typescript

Если вы используете Microsoft Visual Studio, TypeScript можно получить в виде пакета NuGet для проектов MSBuild. Выполните следующую команду в консоли диспетчера пакетов NuGet:

Install-Package Microsoft.TypeScript.MSBuild

Во время установки TypeScript устанавливаются два исполняемых файла: «tsc» — компилятор TypeScript и «tsserver» — автономный сервер TypeScript. Автономный сервер содержит компилятор и языковые службы, которые редакторы и IDE могут использовать для интеллектуального автодополнения кода.

Кроме того, доступны несколько транспиляторов, совместимых с TypeScript, например Babel (через плагин) и swc. Эти транспиляторы можно использовать для преобразования кода TypeScript в другие целевые языки или версии.

TypeScript 7.0 был переписан на Go как нативная реализация компилятора и языковой службы. Он использует многопоточность с общей памятью и другие оптимизации, чтобы ускорить полные сборки и функции редактора, сокращая время обратной связи при разработке.

Некоторые возможности повышения производительности TypeScript 7.0 можно настраивать. Проверку типов можно выполнять параллельно в нескольких обработчиках с помощью --checkers: большее число обработчиков способно ускорить работу с крупными проектами, но требует больше памяти. Переработанный режим --watch улучшает кроссплатформенное отслеживание файлов. В TypeScript 7.0 пока нет API компилятора (по состоянию на июль 2026 года), поэтому инструменты, которым по-прежнему требуется API TypeScript 6.0, могут работать параллельно с TypeScript 7.0 с помощью @typescript/typescript6 или псевдонимов npm.

Настройка

TypeScript можно настроить с помощью параметров командной строки tsc или специального файла конфигурации tsconfig.json, размещённого в корне проекта.

Чтобы создать файл tsconfig.json с рекомендуемыми настройками, можно использовать следующую команду:

tsc --init

При локальном выполнении команды tsc TypeScript скомпилирует код, используя конфигурацию из ближайшего файла tsconfig.json.

Ниже приведены примеры команд CLI, выполняемых с настройками по умолчанию:

tsc main.ts // Compile a specific file (main.ts) to JavaScript
tsc src/*.ts // Compile any .ts files under the 'src' folder to JavaScript
tsc app.ts util.ts --outfile index.js // Compile two TypeScript files (app.ts and util.ts) into a single JavaScript file (index.js)

Файл конфигурации TypeScript

Файл tsconfig.json используется для настройки компилятора TypeScript (tsc). Обычно его размещают в корне проекта вместе с файлом package.json.

Примечания:

• tsconfig.json допускает комментарии, даже несмотря на формат JSON.
• Рекомендуется использовать этот файл конфигурации вместо параметров командной строки.

По следующей ссылке можно найти полную документацию и её схему:

https://www.typescriptlang.org/tsconfig

https://www.typescriptlang.org/tsconfig/

Ниже приведён список распространённых и полезных настроек:

target

Свойство «target» определяет версию ECMAScript, в которую следует преобразовать или скомпилировать код TypeScript. Для современных браузеров хорошим вариантом является ES6. Примечание: поддержка ES5 была объявлена устаревшей в TypeScript 6.0 и больше не поддерживается в TypeScript 7.0.

lib

Свойство «lib» определяет, какие файлы библиотек следует включать во время компиляции. TypeScript автоматически включает API для возможностей, указанных в свойстве «target», однако при необходимости можно исключить или выбрать конкретные библиотеки. Например, при работе над серверным проектом можно исключить библиотеку «DOM», которая полезна только в среде браузера.

strict

Параметр «strict» повышает безопасность типов за счёт включения более строгих проверок. Начиная с TypeScript 6.0 он включён по умолчанию; в противном случае в файле tsconfig.json следует явно задать для него значение true. Включение «strict» позволяет TypeScript выполнять следующие действия:

• Генерировать код с директивой «use strict» для каждого исходного файла.
• Учитывать «null» и «undefined» при проверке типов.
• Запрещать использование типа «any», если аннотации типов отсутствуют.
• Сообщать об ошибке при использовании выражения «this», для которого в противном случае подразумевался бы тип «any».

module

Свойство «module» задаёт систему модулей, поддерживаемую скомпилированной программой. Во время выполнения загрузчик модулей находит и выполняет зависимости в соответствии с указанной системой модулей.

Наиболее распространённые загрузчики модулей в JavaScript — Node.js CommonJS для серверных приложений и RequireJS для модулей AMD в браузерных веб-приложениях. TypeScript может генерировать код для различных систем модулей, включая UMD, System, ESNext, ES2015/ES6 и ES2020. Систему модулей следует выбирать с учётом целевой среды и доступного в ней механизма загрузки модулей.

Примечание: поддержка старых систем модулей (AMD, UMD, SystemJS) была объявлена устаревшей в TypeScript 6.0 и больше не предоставляется в TypeScript 7.0.

moduleResolution

Свойство «moduleResolution» определяет стратегию разрешения модулей. Для современного кода TypeScript используйте «nodenext» или «bundler». Стратегия «classic» используется только в старых версиях TypeScript (до 1.6).

esModuleInterop

Свойство «esModuleInterop» разрешает импорт по умолчанию из модулей CommonJS, в которых экспорт не выполнялся через свойство «default»; это свойство предоставляет прослойку, обеспечивающую совместимость в сгенерированном JavaScript. После включения этого параметра можно использовать import MyLibrary from "my-library" вместо import * as MyLibrary from "my-library".

Изначально «esModuleInterop» был необязательным параметром во избежание обратно несовместимых изменений, но уже давно является рекомендуемой настройкой по умолчанию. Его отключение может привести к неочевидным проблемам во время выполнения при совместном использовании CommonJS и ESM. Примечание: начиная с TypeScript 6.0 это более безопасное поведение совместимости включено всегда.

В TypeScript 6.0 некоторые старые параметры конфигурации и формы синтаксиса были объявлены устаревшими либо переведены в категорию устаревшего поведения. В TypeScript 7.0 они становятся ошибками или не оказывают никакого действия.

Устаревшие возможности, использование которых теперь приводит к критическим ошибкам и не оказывает никакого воздействия:

• target: es5
• downlevelIteration
• moduleResolution: node/node10
• module: amd/umd/systemjs/none
• baseUrl
• moduleResolution: classic
• отключение esModuleInterop или allowSyntheticDefaultImports
• отключение alwaysStrict
• ключевое слово module в объявлениях пространств имён
• asserts в импортах
• /// <reference no-default-lib /> при использовании skipDefaultLibCheck
• пути к файлам в CLI при наличии локального tsconfig.json, если не используется --ignoreConfig

jsx

Свойство “jsx” применяется только к файлам .tsx, используемым в ReactJS, и управляет тем, как конструкции JSX компилируются в JavaScript. Часто используется вариант “preserve”, при котором код компилируется в файл .jsx с сохранением JSX без изменений, чтобы его можно было передать другим инструментам, таким как Babel, для дальнейших преобразований.

skipLibCheck

Свойство “skipLibCheck” запрещает TypeScript выполнять проверку типов во всех импортированных сторонних пакетах. Это свойство сокращает время компиляции проекта. TypeScript по-прежнему будет проверять ваш код на соответствие определениям типов, предоставленным этими пакетами.

files

Свойство “files” указывает компилятору список файлов, которые всегда должны быть включены в программу.

include

Свойство “include” указывает компилятору список файлов, которые требуется включить. Это свойство допускает шаблоны, подобные glob: например, ”*” для любого подкаталога, "" для любого имени файла и ”?” для необязательных символов.

exclude

Свойство “exclude” указывает компилятору список файлов, которые не следует включать в компиляцию. Сюда могут входить такие файлы, как “node_modules”, или тестовые файлы. Примечание: tsconfig.json допускает комментарии.

importHelpers

TypeScript использует вспомогательный код при генерации кода для некоторых расширенных возможностей JavaScript или возможностей, преобразуемых для более ранних версий. По умолчанию эти вспомогательные функции дублируются в использующих их файлах. Вместо этого параметр importHelpers импортирует их из модуля tslib, делая выходной JavaScript-код более эффективным.

Рекомендации по переходу на TypeScript

Для крупных проектов рекомендуется постепенный переход, при котором код на TypeScript и JavaScript поначалу будет сосуществовать. Только небольшие проекты можно перевести на TypeScript за один раз.

Первый шаг этого перехода — внедрить TypeScript в процесс сборки. Это можно сделать с помощью параметра компилятора “allowJs”, который позволяет файлам .ts и .tsx сосуществовать с имеющимися файлами JavaScript. Поскольку TypeScript использует тип “any” для переменной, когда не может вывести тип из файлов JavaScript, в начале миграции рекомендуется отключить “noImplicitAny” в параметрах компилятора.

Второй шаг — убедиться, что тесты JavaScript работают вместе с файлами TypeScript, чтобы можно было запускать тесты по мере преобразования каждого модуля. Если вы используете Jest, рассмотрите возможность применения ts-jest, который позволяет тестировать проекты TypeScript с помощью Jest.

Третий шаг — добавить в проект объявления типов для сторонних библиотек. Эти объявления могут поставляться вместе с библиотеками или находиться в DefinitelyTyped. Их можно найти с помощью https://www.typescriptlang.org/dt/search и установить следующим образом:

npm install --save-dev @types/package-name

или

yarn add --dev @types/package-name

Четвёртый шаг — выполнять миграцию модуль за модулем, следуя восходящему подходу и начиная с листьев графа зависимостей. Идея состоит в том, чтобы начать преобразование с модулей, которые не зависят от других модулей. Для визуализации графов зависимостей можно использовать инструмент “madge”.

Хорошими кандидатами для первоначального преобразования являются служебные функции и код, связанный с внешними API или спецификациями. Можно автоматически создавать определения типов TypeScript из контрактов Swagger, схем GraphQL или JSON для включения в проект.

Если спецификации или официальные схемы недоступны, типы можно создать на основе необработанных данных, например JSON, возвращаемого сервером. Однако рекомендуется создавать типы на основе спецификаций, а не данных, чтобы не упустить пограничные случаи.

Во время миграции воздержитесь от рефакторинга кода и сосредоточьтесь исключительно на добавлении типов в модули.

Пятый шаг — включить “noImplicitAny”, что потребует, чтобы все типы были известны и определены, и улучшит работу с TypeScript в проекте.

Во время миграции можно использовать директиву @ts-check, которая включает проверку типов TypeScript в файле JavaScript. Эта директива предоставляет менее строгую версию проверки типов и на начальном этапе может использоваться для выявления проблем в файлах JavaScript. Если файл содержит @ts-check, TypeScript попытается вывести определения с помощью комментариев в стиле JSDoc. Однако следует использовать аннотации JSDoc только на самом раннем этапе миграции.

Рассмотрите возможность сохранить для noEmitOnError в файле tsconfig.json значение по умолчанию false. Это позволит создавать исходный код JavaScript, даже если были обнаружены ошибки.