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

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

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

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

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

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

            tsc --init
            

              
                Copy
              
            
          

Эта команда создает базовый файл 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"
  }
}
            

              
                Copy
              
            
          

module

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

Пример:

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

              
                Copy
              
            
          

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"]
  }
}
            

              
                Copy
              
            
          

allowJs

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

Пример:

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

              
                Copy
              
            
          

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"
  }
}
            

              
                Copy
              
            
          

declaration

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

Пример:

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

              
                Copy
              
            
          

sourceMap

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

Пример:

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

              
                Copy
              
            
          

outDir

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

Пример:

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

              
                Copy
              
            
          

rootDir

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

Пример:

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

              
                Copy
              
            
          

strict

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

Пример:

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

              
                Copy
              
            
          

esModuleInterop

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

Пример:

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

              
                Copy
              
            
          

moduleResolution

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

Пример:

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

              
                Copy
              
            
          

baseUrl и paths

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

Пример:

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

              
                Copy
              
            
          

Опции Include и Exclude

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

Пример:

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

              
                Copy
              
            
          

Опция Extends

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

Пример:

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

              
                Copy
              
            
          

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

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

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

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

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

              
                Copy
              
            
          

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

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

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

              
                Copy
              
            
          

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

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

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

              
                Copy
              
            
          

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

• Используйте строгий режим: Включите опцию strict для улучшенной проверки типов.
• Указывайте цель: Выбирайте подходящую версию target для вашей среды выполнения.
• Организуйте вывод: Используйте outDir для отделения исходного кода от скомпилированного.
• Управляйте зависимостями: Используйте include и exclude для контроля над тем, какие файлы компилируются.
• Используйте extends: Делитесь общими настройками конфигурации с помощью опции extends.
• Добавляйте конфигурацию в систему контроля версий: Коммитьте `tsconfig.json` в git для поддержания согласованности между средами разработки и в конвейерах CI/CD.

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

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

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

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

Ошибки типов

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

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

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

Заключение

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

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