TypeScript. Начало работы, часть 1 из 7

TypeScript — типизированное надмножество JavaScript, предназначенное для выявления ошибок на этапе компиляции. Код на TypeScript компилируется в код JavaScript, который выполняется в любом браузере. Эта надстройка вокруг основного языка JavaScript дает разработчикам статическую типизацию и приведение типов.

$ npm install -g typescript

Опции компиляции

При компиляции файлов TypeScript в файлы JavaScript из командной строки с помощью компилятора tsc можно задать множество опций.

Опция -w или --watch автоматически перекомпилирует файлы typescript, если в них были внесены какие-либо изменения. Благодаря чему не надо при каждом изменении вручную вводить команду в консоль для перекомпиляции.

$ tsc --watch app.ts

С помощью опции -t или --target можно задать версию стандарта JavaScript, в которую будет компилироваться код TypeScript.

$ tsc --target es5 app.ts

По умолчанию в файлы JavaScript переносятся все комментариии, которыми снабжен код в файлах TypeScript. Удаление комментариев при компиляции осуществляется с помощью опции --removeComments.

$ tsc --removeComments app.ts

С помощью опции --outDir можно задать директорию для хранения скомпилированных файлов JavaScript.

$ tsc --outDir ./build/js app.ts

Если есть несколько файлов TypeScript, то с помощью опции --outFile их можно объединить в один файл JavaScript.

$ tsc --outFile output.js app.ts core.ts

С помощью опции -m или --module можно указать тип модульной системы, которую будет использовать скомпилированное приложение.

$ tsc --module commonjs app.ts

Опция --noEmit позволяет не создавать выходные javascript файлы, но посмотреть на ошибки, которые возникают при компиляции.

$ tsc --noEmit

Опция --init позволяет создать файл настройки tsconfig.json проекта TypeScript (см.ниже).

$ tsc --init

Чтобы посмотреть все доступные опции и справку по ним, можно воспользоваться опцией -h или --help.

$ tsc --help
tsc: The TypeScript Compiler - Version 4.9.4

COMMON COMMANDS

  tsc
  Compiles the current project (tsconfig.json in the working directory.)

  tsc app.ts util.ts
  Ignoring tsconfig.json, compiles the specified files with default compiler options.

  tsc -b
  Build a composite project in the working directory.

  tsc --init
  Creates a tsconfig.json with the recommended settings in the working directory.

  tsc -p ./path/to/tsconfig.json
  Compiles the TypeScript project located at the specified path.

  tsc --help --all
  An expanded version of this information, showing all possible compiler options

  tsc --noEmit
  tsc --target esnext
  Compiles the current project, with additional settings.

COMMAND LINE FLAGS

--help, -h
Print this message.

--watch, -w
Watch input files.

--all
Show all compiler options.

--version, -v
Print the compiler's version.

--init
Initializes a TypeScript project and creates a tsconfig.json file.

--project, -p
Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.

--build, -b
Build one or more projects and their dependencies, if out of date

--showConfig
Print the final configuration instead of building.

COMMON COMPILER OPTIONS

--pretty
Enable color and formatting in TypeScript's output to make compiler errors easier to read.
type: boolean
default: true

--target, -t
Set the JavaScript language version for emitted JavaScript and include compatible library declarations.
one of: es3, es5, es6/es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, esnext
default: es3

--module, -m
Specify what module code is generated.
one of: none, commonjs, amd, umd, system, es6/es2015, es2020, es2022, esnext, node16, nodenext
default: undefined

--lib
Specify a set of bundled library declaration files that describe the target runtime environment.
one or more: es5, es6/es2015, es7/es2016, es2017, es2018, es2019, es2020, es2021, es2022, esnext,
dom, dom.iterable, webworker, webworker.importscripts, webworker.iterable, scripthost, es2015.core,
es2015.collection, es2015.generator, es2015.iterable, es2015.promise, es2015.proxy, es2015.reflect,
es2015.symbol, es2015.symbol.wellknown, es2016.array.include, es2017.object, es2017.sharedmemory,
es2017.string, es2017.intl, es2017.typedarrays, es2018.asyncgenerator, es2018.asynciterable/esnext.asynciterable,
es2018.intl, es2018.promise, es2018.regexp, es2019.array, es2019.object, es2019.string, es2019.symbol/esnext.symbol,
es2019.intl, es2020.bigint/esnext.bigint, es2020.date, es2020.promise, es2020.sharedmemory, es2020.string,
es2020.symbol.wellknown, es2020.intl, es2020.number, es2021.promise/esnext.promise, es2021.string,
es2021.weakref/esnext.weakref, es2021.intl, es2022.array/esnext.array, es2022.error, es2022.intl,
es2022.object, es2022.sharedmemory, es2022.string/esnext.string, esnext.intl
default: undefined

--allowJs
Allow JavaScript files to be a part of your program. Use the 'checkJS' option to
get errors from these files.
type: boolean
default: false

--checkJs
Enable error reporting in type-checked JavaScript files.
type: boolean
default: false

--jsx
Specify what JSX code is generated.
one of: preserve, react, react-native, react-jsx, react-jsxdev
default: undefined

--declaration, -d
Generate .d.ts files from TypeScript and JavaScript files in your project.
type: boolean
default: `false`, unless `composite` is set

--declarationMap
Create sourcemaps for d.ts files.
type: boolean
default: false

--emitDeclarationOnly
Only output d.ts files and not JavaScript files.
type: boolean
default: false

--sourceMap
Create source map files for emitted JavaScript files.
type: boolean
default: false

--outFile
Specify a file that bundles all outputs into one JavaScript file. If 'declaration'
is true, also designates a file that bundles all .d.ts output.

--outDir
Specify an output folder for all emitted files.

--removeComments
Disable emitting comments.
type: boolean
default: false

--noEmit
Disable emitting files from a compilation.
type: boolean
default: false

--strict
Enable all strict type-checking options.
type: boolean
default: false

--types
Specify type package names to be included without being referenced in a source file.

--esModuleInterop
Emit additional JavaScript to ease support for importing CommonJS modules.
This enables 'allowSyntheticDefaultImports' for type compatibility.
type: boolean
default: false

You can learn about all of the compiler options at https://aka.ms/tsc

Файл tsconfig.json

С помощью файла tsconfig.json можно настроить проект TypeScript — установить корневой каталог и имена файлов + задать значения параметров компиляции.

{
    "compilerOptions": {
        "target": "es2015",           // скомпилировать в javascript стандарта ES2015
        "moduleResolution": "node16", // как разрешать модули при компиляции typescript
        "module": "es2015",           // javascript код будет использовать модули ES2015
        "outDir": "build",            // директория для скомпилированных javascript файлов
        "strict": true,               // включить все опции группы Strict Checks
        "sourceMap": true,            // при компиляции создавать карту кода
        "removeComments": true,       // удалить комментарии в javascript файлах
        "newLine": "lf",              // новая строка в javascript файлах — как в Linux
        "esModuleInterop": true,      // импортировать модули CommonJS как модули ES2015
        "forceConsistentCasingInFileNames": true
    },
    "files": [
        "src/ts/core.ts",
        "src/ts/app.ts"
    ]
}

Опция extends

Указывает путь к файлу из которого нужно унаследовать опции. По большей части, служит инструментом упорядочивания. Можно разделить опции по некой логике, чтобы они не смешивались. Допустим, нам нужно создать production и development версии настроек — так бы мог выглядеть файл tsconfig-dev.json.

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        // переопределяем настройки, которые нужны только для dev режима
        "sourceMap": true,
        "watch": true
    }
}

При использовании extends увидеть итоговую, объединённую версию настроек можно с помощью команды

$ tsc --showConfig

Опция files

Указывает список конкретных файлов для компиляции — подходит лишь для совсем маленьких проектов из нескольких файлов.

{
    "compilerOptions": {},
    "files": [
        "src/ts/core.ts",
        "src/ts/app.ts"
    ]
}

Опция include

Используется для поиска компилируемых файлов, если не указана опция files. Если include тоже не указана, то её значение будет неявно объявлено как ["**/*"]. Это означает, что поиск файлов будет осуществляться во всех директориях и поддиректориях. Такое поведение не оптимально, поэтому в целях производительности лучше всегда указывать конкретные пути. Можно прописывать как пути к конкретным файлам, так и шаблоны путей.

{
    "compilerOptions": {},
    "include": [
        "src/**/*",
        "test/**/*"
    ]
}

Если шаблоны не указывают конкретных расширений файлов, то поиск будет включать только .ts, .tsx и .d.ts. Чтобы включить в поиск файлы .js и .jsx — нужно указать allowJs:true внутри compilerOptions.

Технически, с помощью опций include и exclude, будет сформирован список файлов и помещен в files. Это можно увидеть, если выполнить команду tsc --showConfig.

Опция exclude

Позволяет исключить некоторые лишние пути или файлы, которые бфли добавлены в список с помощью опции include. По умолчанию, опция имеет значение путей пакетных менеджеров npm, bower и jspm, так как модули в них уже собраны. Помимо этого, игнорируется директория из опции outDir, если она указана.

Если добавить свои значения в эту опцию — важно не забыть восстановить умолчания. Так как пользовательские значения не объединяются со значениями по умолчанию. Другими словами, необходимо вручную указать корень модулей своего пакетного менеджера.

{
    "compilerOptions": {},
    "include": [
        "src/**/*"
    ],
    "exclude": [
        "node_modules",
        "src/**/*.spec.ts"
    ]
}

Секция compilerOptions

Опция target

Значение по умолчанию — es3. Изменение значения target изменяет значение по умолчанию для lib.

Версия стандарта ECMAScript, в которую будет скомпилирован TypeScript код — es3, es5, es6 (или es2015), es7 (или es2016), es2017, es2018, es2019, es2020, es2021, es2022, esnext.

Для frontend-приложений можно выбрать es6 — большинство браузеров его поддерживают. Чтобы обеспечить работу кода в старых браузерах — можно выбрать es5. Для backend-приложений подойдёт es6 для новых версий Node.js и значение es5 — для старых.

Опция module

Значение по умолчанию зависит от target.

Модульная система, которую будет использовать собранное приложение — none, commonjs, amd, system, umd, es6 (или es2015), es2020, es2022, esnext, node16, nodenext. Для backend-приложений подойдёт es6 или commonjs в зависимости от версий Node.js, которые нужно поддерживать. Для frontend-приложений под современные браузеры подходит es6, под старые браузеры — значение umd.

Значения node16 и nodenext предназначены для последних версий Node.js, где реализована поддержка ECMAScript модулей. Скомпилированный JavaScript использует CommonJS или ESM (ES module) — в зависимости от расширения файла и значения параметра type в ближайшем файле package.json.

Опция moduleResulution

Значение по умолчанию зависит от module.

Стратегия, которую будет использовать компилятор для импорта модулей, зависит от module. Значение node — использовать модули CommonJS, значение node16 или nodenext — использовать модули ECMAScript, classic — для обратной совместимости, не рекомендуется использовать.

Опция lib

Значение по умолчанию зависит от target.

TypeScript включает в себя набор определений типов для встроенных API-интерфейсов JavaScript (например, Math), а также определения типов для вещей, которые можно найти в среде браузера (например, document). TypeScript также включает API для новых функций JavaScript, соответствующих указанному target — например, определение для Map доступно, если target:es6 или новее.

Причина для изменения значения lib — необычная среда выполнения скомпилированного кода. Например, приложение не предназначено для работы в браузере, поэтому не нужны DOM определения типов. Или, среда выполнения предоставляет определенные объекты API JavaScript (возможно, посредством полифиллов), но еще не поддерживает полный синтаксис данной версии ECMAScript.

• По умолчанию для target:es5 подключаются DOM, ES5, ScriptHost
• По умолчанию для target:es6 подключаются DOM, ES6, DOM.Iterable, ScriptHost

При изменении значения lib умолчания сбрасываются — это значит, что нужно руками добавить то, что необходимо.

Опция outDir

Значение по умолчанию равно корневой директории проекта.

Конечная директория, куда будут помещаться скомпилированные javascript-файлы. Если не указывать значение этой опции, то все javascript-файлы будут повторять структуру typescript-файлов в корне проекта.

Если оставить опцию outDir пустой

├── module
│   └── core.js
│   └── core.ts
├── index.js
└── index.ts

Если указать значение опции outDir

├── dist
│   └── module
│   |   └── core.js
│   └── index.js
├── module
│   └── core.ts
└── index.ts

Опция outFile

Значение по умолчанию — none.

Судя по описанию, данная опция позволяет объединить все файлы в один. Кажется, что сборщики больше не нужны — однако, опция не будет работать с модулями CommonJS или ES2015. Опция позволяет только объединить все глобальные (немодульные) файлы в один указанный выходной файл. Опция работает, только если значение module указано как None, System или AMD. Так что особого смысла в ее использовании нет.

Опция allowSyntheticDefaultImports

Значение по умолчанию зависит от module или esModuleInterop.

Опция позволяет предотвращать ошибки компиляции по причине несовместимости модулей ES2015 и CommonJS. Чаще всего проблема возникает в случае, когда разработка ведется с применением одних модулей, а подключаемые библиотеки используют другие. В ES2015 синтаксисе есть возможность экспорта и импорта по умолчанию. С другой стороны, подключаемый модуль CommonJS может не иметь экспорта по умолчанию. При импорте по умолчанию такого модуля — возникает ошибка.

Для удобства разработчиков транспиляторы, такие как Babel, автоматически создают экспорт по умолчанию, если модуль его не содержит. Опция приводит поведение TypeScript в соответствие с Babel — так что при компиляции не будет ошибки «module has no default export». Опция включена по умолчанию, если включена опция esModuleInterop. При этом, опция никак не влияет на результирующий javascript код, но позволяет писать код следующим образом.

// вместо такого импорта
import * as React from 'react';
// можно писать такой
import React from 'react';

Опция esModuleInterop

Значение по умолчанию — false.

За счёт добавления болерплейта в выходной код, позволяет импортировать модули CommonJS как как модули ES2015. Опция по зависимости активирует allowSyntheticDefaultImports. Вместе они помогают избавиться от зоопарка разных импортов и писать их единообразно по всему проекту. Рекомендуется всегда выставлять опцию в значение true.

Опция alwaysStrict

Значение по умолчанию — false. Если включена опция strict, тогда true.

Компилятор будет парсить код в strict mode и добавлять use strict в выходные javascript файлы.

Опция downlevelIteration

Значение по умолчанию — false.

Спецификация ES2015 добавила новый синтаксис для итерирования: цикл for/of, расширение массива [a, ...b], расширение аргумента fn(...args) и Symbol.iterator. Если код проекта преобразовывается в ES5, то конструкция с циклом for/of будет преобразована в обычный цикл for.

Однако, некоторые символы, такие как emoji кодируются с помощью двух символов. Т.е. такое преобразование в некоторых местах будет работать не так, как ожидается. Значение true генерирует более многословный и более правильный, но менее производительный код.

Опция forceConsistentCasingInFileNames

Значение по умолчанию — false.

Включает режим чувствительности к регистру (case-sensitive) для импорта файлов. Таким образом, даже в case-insensitive файловых системах при попытке сделать импорт FileManager.ts, если файл в действительности файл называется fileManager.ts, приведёт к ошибке.

Опция declaration

Значение по умолчанию — false.

С помощью включения данного флага, помимо javascript файлов, будут создаваться файлы-аннотации, известные как d.ts-файлы или тайпинги. Благодаря тайпингам становится возможным определение типов для уже скомпилированных javascript файлов. Другими словами, код попадает в js-файлы, а типы — в d.ts-файлы. Это полезно в случае публикации пакета в npm. Такой библиотекой смогут пользоваться разработчики, которые пишут как на чистом JavaScript, так и на TypeScript.

Опция declarationDir

Значение по умолчанию — none, связано с опцией declaration.

По умолчанию тайпинги генерируются рядом с javascript-файлами. Используя данную опцию можно перенаправить все d.ts-файлы в отдельную директорию.

Опция allowJs

Значение по умолчанию — false, зависит от checkJs.

Разрешить компилятору обрабатывать не только typescript-файлы, но и javascript-файлы. Опция можно использовать для постепенного перехода проекта от JavaScript к TypeScript, позволяя файлам .ts и .tsx жить вместе с файлами .js и .jsx. Старые jvascript-файлы можно постепенно заменять новыми typescript-файлами, просто меняя расширение и добавляя типизацию.

Опция checkJs

Значение по умолчанию — false. При включении checkJs — автоматически включается allowJs.

TypeScript будет проверять ошибки не только в typescript-файлах, но и в javascript-файлах. Помимо встроенных тайпингов для языковых конструкций JavaScript, компилятор так же умеет использовать jsDoc для анализа файлов.

Опция resolveJsonModule

Значение по умолчанию — false.

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

// необходимо указывать расширение .json
import config from './config.json';

Опция jsx

Значение по умолчанию — none.

Если проект использует React, необходимо включить поддержку JSX:

• значение preserve сохранит JSX-код для дальнейшего преобразования в javascript, выходной файл будет иметь расширение .jsx
• значение react преобразует JSX-код в вызовы React.createElement, не требует дальнейшего преобразования, выходной файл будет .js
• значение react-native эквивалентно preserve в том смысле, что сохраняется JSX-код, но выходной файл будет иметь расширение .js.

Начиная с TypeScript 4.1 допускаются значения react-jsx и react-jsxdev — для поддержки React 17, где в коде можно опускать импорт React.

Дополнительно

• Раскладываем tsconfig.json по полочкам, часть 1
• Раскладываем tsconfig.json по полочкам, часть 2
• Руководство по TypeScript
• Intro to the TSConfig Reference
• Centralized Recommendations for TSConfig bases

Поиск: JavaScript • Web-разработка • Теория • Типы данных • TypeScript • tsconfig.json

• Web-разработка
  • HTML и CSS
  • JavaScript и TypeScript
  • PHP и MySQL
  • CMS Битрикс
  • CMS WoprdPress
  • Yii2 и Laravel
  • Python и Flask
  • Web-аналитика
  • Разное
• ОС Linux
  • Команды
  • Сценарии
  • Разное
• 1С:Предприятие
  • Программирование
  • Язык запросов
  • Разное
• Локальная сеть
  • Разное

• 1С:Предприятие (31)
• API (29)
• Bash (43)
• CLI (126)
• CMS (139)
• CSS (50)
• Frontend (75)
• HTML (66)
• JavaScript (150)
• Laravel (72)
• Linux (174)
• MySQL (76)
• PHP (125)
• React.js (66)
• SSH (27)
• Ubuntu (70)
• Web-разработка (509)
• WordPress (73)
• Yii2 (69)
• БазаДанных (95)
• Битрикс (66)
• Блог (29)
• Верстка (43)
• ИнтернетМагаз… (84)
• КаталогТоваров (87)
• Класс (30)
• Клиент (29)
• Ключ (28)
• Команда (88)
• Компонент (60)
• Конфигурация (72)
• Корзина (32)
• ЛокальнаяСеть (33)
• Модуль (34)
• Навигация (31)
• Настройка (148)
• ПанельУправле… (29)
• Плагин (33)
• Пользователь (26)
• Практика (101)
• Сервер (82)
• Событие (28)
• Теория (106)
• Установка (72)
• Файл (51)
• Форма (58)
• Фреймворк (192)
• Функция (36)
• ШаблонСайта (68)

• Web-разработка
• 1С:Предприятие
• ОС Linux
• Регулярные выражения
• Разное