M

MLOG

Русский

Освойте конфигурацию TypeScript с помощью этого подробного руководства по tsconfig.json. Изучите основные параметры компилятора, настройку проекта и расширенные конфигурации для эффективной разработки.

Конфигурация TypeScript: подробное руководство по tsconfig.json

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

Что такое tsconfig.json?

Файл tsconfig.json — это конфигурационный файл, который определяет параметры компилятора для проекта TypeScript. Он указывает компилятору TypeScript, как транспилировать код TypeScript в JavaScript. Этот файл необходим для определения структуры проекта, установки правил компиляции и обеспечения согласованности в команде разработчиков, независимо от того, находится ли эта команда в одном офисе или распределена по нескольким континентам.

Создание файла tsconfig.json

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

tsc --init

Эта команда создает базовый файл tsconfig.json с часто используемыми параметрами компилятора. Затем вы можете настроить файл в соответствии с конкретными требованиями вашего проекта. Типичный tsconfig.json будет включать такие опции, как compilerOptions, include и exclude.

Основные параметры компилятора

Раздел compilerOptions — это сердце файла tsconfig.json. Он содержит широкий спектр опций, которые управляют поведением компилятора TypeScript. Вот некоторые из наиболее важных параметров компилятора:

target

Опция target указывает целевую версию ECMAScript для сгенерированного кода JavaScript. Распространенные значения включают ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Выбор правильной цели имеет решающее значение для обеспечения совместимости с предполагаемой средой выполнения, такой как браузеры или версии Node.js.

Пример:

{
  "compilerOptions": {
    "target": "ES2020"
  }
}

module

Опция module указывает стиль генерации кода модулей. Распространенные значения включают CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 и ESNext. Выбор системы модулей зависит от целевой среды и используемого сборщика модулей (например, Webpack, Rollup, Parcel). Для Node.js часто используется CommonJS, в то время как для современных веб-приложений предпочтительнее ES6 или ESNext со сборщиком модулей. Использование ESNext позволяет разработчикам использовать самые последние функции и оптимизации, полагаясь на сборщик для обработки конечного формата модуля.

Пример:

{
  "compilerOptions": {
    "module": "ESNext"
  }
}

lib

Опция lib указывает список файлов библиотек, которые будут включены в компиляцию. Эти файлы библиотек предоставляют определения типов для встроенных API JavaScript и API браузера. Распространенные значения включают ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String и многие другие. Выбор подходящих библиотек гарантирует, что компилятор TypeScript будет иметь необходимую информацию о типах для целевой среды. Использование библиотеки DOM позволяет проекту компилировать код, использующий специфичные для браузера API, без ошибок типов.

Пример:

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

allowJs

Опция allowJs позволяет компилятору TypeScript компилировать файлы JavaScript вместе с файлами TypeScript. Это полезно для постепенного переноса существующих проектов JavaScript на TypeScript. Установка этого параметра в true позволяет компилятору обрабатывать файлы .js, что делает возможным постепенное внедрение TypeScript в проект.

Пример:

{
  "compilerOptions": {
    "allowJs": true
  }
}

jsx

Опция jsx указывает, как следует обрабатывать синтаксис JSX. Распространенные значения включают preserve, react, react-native и react-jsx. preserve сохраняет синтаксис JSX в выводе, в то время как react преобразует JSX в вызовы React.createElement. react-jsx использует новое преобразование JSX, введенное в React 17, которое не требует импорта React. Выбор правильной опции JSX имеет решающее значение для проектов, использующих React или другие библиотеки на основе JSX.

Пример:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

declaration

Опция declaration генерирует соответствующие файлы объявлений .d.ts для каждого файла TypeScript. Файлы объявлений содержат информацию о типах и используются другими проектами TypeScript для потребления скомпилированного кода. Генерация файлов объявлений необходима для создания переиспользуемых библиотек и модулей. Эти файлы позволяют другим проектам TypeScript понимать типы и интерфейсы, предоставляемые библиотекой, без необходимости компилировать исходный код.

Пример:

{
  "compilerOptions": {
    "declaration": true
  }
}

sourceMap

Опция sourceMap генерирует файлы sourcemap, которые сопоставляют сгенерированный код JavaScript с исходным кодом TypeScript. Исходные карты необходимы для отладки кода TypeScript в браузерах и других средах. Когда в коде JavaScript возникает ошибка, исходная карта позволяет разработчику увидеть соответствующий код TypeScript в отладчике, что облегчает выявление и устранение проблемы.

Пример:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

outDir

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

Пример:

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

rootDir

Опция rootDir указывает корневой каталог проекта TypeScript. Компилятор использует этот каталог в качестве основы для разрешения имен модулей. Эта опция особенно важна для проектов со сложной структурой каталогов. Правильная настройка rootDir гарантирует, что компилятор сможет найти все необходимые модули и зависимости.

Пример:

{
  "compilerOptions": {
    "rootDir": "src"
  }
}

strict

Опция strict включает все строгие параметры проверки типов. Это настоятельно рекомендуется для новых проектов TypeScript, так как помогает выявлять потенциальные ошибки на ранних этапах процесса разработки. Включение строгого режима обеспечивает более строгие правила проверки типов, что приводит к более надежному и поддерживаемому коду. Включение строгого режима во всех новых проектах TypeScript является лучшей практикой.

Пример:

{
  "compilerOptions": {
    "strict": true
  }
}

esModuleInterop

Опция esModuleInterop обеспечивает совместимость между модулями CommonJS и ES. Это важно для проектов, которые используют оба типа модулей. Когда esModuleInterop включен, TypeScript автоматически обрабатывает различия между модулями CommonJS и ES, что упрощает импорт и экспорт модулей между двумя системами. Эта опция особенно полезна при работе со сторонними библиотеками, которые могут использовать разные системы модулей.

Пример:

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

moduleResolution

Опция moduleResolution указывает, как TypeScript разрешает импорт модулей. Распространенные значения включают Node и Classic. Стратегия разрешения модулей Node является стандартной и основана на алгоритме разрешения модулей Node.js. Стратегия разрешения модулей Classic является более старой и используется реже. Использование стратегии разрешения модулей Node гарантирует, что TypeScript сможет правильно разрешать импорт модулей в среде Node.js.

Пример:

{
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

baseUrl и paths

Опции baseUrl и paths используются для настройки разрешения модулей для не-относительных импортов. Опция baseUrl указывает базовый каталог для разрешения не-относительных имен модулей. Опция paths позволяет сопоставлять имена модулей с конкретными местоположениями в файловой системе. Эти опции особенно полезны для проектов со сложной структурой каталогов и для упрощения импорта модулей. Использование baseUrl и paths может сделать код более читаемым и поддерживаемым.

Пример:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Опции Include и Exclude

Опции include и exclude указывают, какие файлы должны быть включены в компиляцию, а какие — исключены. Эти опции используют glob-шаблоны для сопоставления имен файлов. Использование include и exclude позволяет контролировать, какие файлы обрабатываются компилятором TypeScript, улучшая производительность сборки и уменьшая количество ошибок. Явное указание файлов для компиляции является лучшей практикой.

Пример:

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Опция Extends

Опция extends позволяет наследовать параметры компилятора из другого файла tsconfig.json. Это полезно для совместного использования общих настроек конфигурации между несколькими проектами или для создания базовых конфигураций. Использование опции extends способствует переиспользованию кода и уменьшает дублирование. Создание базовых конфигураций и их расширение в отдельных проектах является лучшей практикой.

Пример:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

Расширенные конфигурации

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

Инкрементальная компиляция

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

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Ссылки на проекты (Project References)

Ссылки на проекты позволяют структурировать большие проекты TypeScript на более мелкие, независимые модули. Это может улучшить время сборки и организацию кода. Использование ссылок на проекты может сделать большие проекты более управляемыми и легкими в поддержке. Использование ссылок на проекты для больших и сложных проектов является лучшей практикой.

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

Пользовательские определения типов

Иногда вам может потребоваться предоставить определения типов для библиотек JavaScript, у которых их нет. Вы можете создать пользовательские файлы .d.ts для определения типов этих библиотек. Создание пользовательских определений типов позволяет использовать библиотеки JavaScript в вашем коде TypeScript без ущерба для безопасности типов. Это особенно полезно при работе с унаследованным кодом JavaScript или библиотеками, которые не предоставляют свои собственные определения типов.

// custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

Лучшие практики

Устранение распространенных проблем

Настройка tsconfig.json иногда может быть сложной. Вот некоторые распространенные проблемы и их решения:

Проблемы с разрешением модулей

Если вы сталкиваетесь с ошибками разрешения модулей, убедитесь, что опция moduleResolution настроена правильно и что опции baseUrl и paths установлены должным образом. Дважды проверьте пути, указанные в опции paths, чтобы убедиться в их корректности. Убедитесь, что все необходимые модули установлены в каталоге node_modules.

Ошибки типов

Ошибки типов могут возникать, если определения типов неверны или отсутствуют. Убедитесь, что у вас установлены правильные определения типов для всех используемых библиотек. Если вы используете библиотеку JavaScript, у которой нет определений типов, рассмотрите возможность создания пользовательских определений типов.

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

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

Заключение

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

Не забывайте обращаться к официальной документации TypeScript за самой актуальной информацией и подробными объяснениями всех доступных параметров компилятора. Документация TypeScript — это ценный ресурс для понимания тонкостей конфигурации TypeScript.