tsconfig 常用配置项

tsconfig 常用配置项

基于typescript的项目的根目录下都会有一个文件(tsconfig.json), 这个文件主要用来控制typescript编译器(tsc, typescript compiler)的一些行为, 比如指定哪些文件需要让tsc来编译, 哪些文件不想让tsc进行编译之类的。通常会配合eslint配置@typescript-eslint做代码检测。

tsconfig的作用范围 — include/files/exclude

通过这三个配置项的配合使用可定义ts作用的文件范围

include: 指定要编译文件的白名单,在这个白名单里被匹配到的文件才会被tsc处理编译;字符串数组

exclude: 指定要编译文件的白名单,在这个白名单里被匹配到的文件才会被tsc处理编译

files: 配置的作用类似include, 也是一个白名单路径数组, 不同在于它不能使用通配符, 而必须使用精确的文件路径(可以是相对路径)

// global.d.ts

// 声明Window对象中的Tracker对象；常用于给Window添加方法或属性
interface Window {
  Tracker: any
}
// 对于第三方库，如果tsconfig.json中的noImpliciAny为true，那么当你在代码中import时会发现eslint报错“无法找到模块的声明文件”。这时候有两种方式解决：1. 声明模块 -- declare module 文件名。 2. 根据报错提示尝试安装该库的TypeScript版本 -- npm install -D @types。方法二不一定能解决问题，因为可能库里没有他的声明文件。
declare module 'palife-h5-util'
// 声明全局变量；常用于通过script引入方法库，且变量以全局变量的方式提供
declare const ULink: any

{
  include: [
    "./src/**/*", // 解析src目录下的文件
    "global.d.ts" // 解析global.d.ts全局类型文件，如上
  ],
  files: [
    "./src/index.ts" // 项目入口文件, 那么就可以使用在只用files配置这个文件的路径, 然后其他的文件都通过index.ts来import
  ],
  exclude: [
    "./src/cli/bin/**/*" // 排除掉src目录中的cli/bin下掉文件
  ]
}

扩展tsconfig — extends

extends 用于在一个tsconfig.json文件中扩展其他tsconfig.json文件; 如输出文件的tsconfig.build.json配置如下

{
  extend: "./tsconfig.json",
  compilerOptions: {
    "declaration": true,
    "outDir": "./dist"
  },
  "exclude": [
    "./src/**/__test__"
  ]
}

编译器配置 — compilerOptions

compilerOptions配置编辑器的属性

paths — 路径映射

paths是文件映射配置；webpack中会用alias来重定向文件或者babel配置文件重定向，在tsconfig中要对alias中的文件映射定义一遍; paths是相对于baseUrl的

paths 路径映射是模块并非相对或绝对路径。即import from 'palife-lib-fluid/base-lib',对于import from './palife-lib-fluid/base-lib'或者import from '/palife-lib-fluid/base-lib'是无效的！

// webpack.resolve.alias
{
  alias: {
    ROOT: path.resolve(__dirname, './src')
  }
}
  
// babel.config.js
  module.exports = {
    presets: ['module:metro-react-native-babel-preset'],
    plugins: [
      ['@babel/plugin-proposal-decorator', { legacy: true }],
      ['module-resolver', {
        root: ['./'],
        alias: {
          'palife-lib-fluid': './src'
        }
      }]
    ]
  }

// tsconfig.json
// compilerOptions.paths
{
  baseUrl: "./",
  paths: {
    "palife-lib-fluid/*": [
      "src/*"
    ]
  }
}

从上面可看到paths对象属性值是数组而非字符串，这是为何呢？其实值为数组的目的是让模块路径解析可以有多个fallback。例如下面，解析模块时会先在template目录中查找文件，如果查找不到再到src/template目录中寻找，如果src/template也找不到文件才会报错。

// tsconfig.compilerOptions
{
  "baseUrl": './'
  "path": {
    "template/*": [
      "template/*",
      "src/template/*"
    ]
  }
}

注意typescript只是在开发过程中协助功能，最终并不会落地。paths配置路径映射只是做源码开发时类型限制，尽管eslint不会报错，但源码文件模块解析是否成功还是取决于项目构建过程及模块解析配置。譬如webpack的resolve.module配置模块解析方式及resolve.alias配置别名。或者构建过程会出现文件结构变动,如上面试例，构建过程会把根目录下的template文件合并到src/template目录。

rootDirs — 虚拟目录

有时，编译时来自多个目录的项目源都被组合在一起以生成单个输出目录。这可以看作是一组源目录创建一个"虚拟"目录，就像paths中的template的例子，它也可通过rootDirs来实现。只不过rootDirs只能设置一个虚拟目录，不能像paths可以设置任意多个。

rootDirs设置多个目录为同一个上下文，即把不同目录当作同一个目录。

{
  "baseUrl": './'
  "rootDirs": [
    "src/local/zh",
  	"src/local/en",
  	"src/local/#{locale}"
  ]
}

上面配置ts编辑器会把./src/local/zh、./src/local/en、./src/local/#{locale}三个目录当作同一个目录。即使声明的路径不存在也可

const Common from './local/#{locale}/common'
// 1. 首先会去寻找 ./src/local/#{locale}/common， 因为 #{locale}目录是不存在的，所以走2逻辑
// 2. 首先会去寻找 ./src/local/zh/common， 如果存在该文件就用这个，否则继续走3逻辑
// 3. 寻找 ./src/local/en/common, 如果存在该文件就用这个，否则eslint报错

以上事例适用于在代码运行时会根据环境去替换源码中的#{locale}来设置语言包，但是eslint检测不到./local/#{locale}/common模块，如上设置就可解决找不到模块eslint的问题。

typeRoots — 类型文件根目录

typeRoots用来指定默认的类型声明文件查找路径，默认是包含所有node_module/@types。会加载typeRoots目录下的所有直属文件夹中的类型声明文件，index.d.ts或者package.types指向的文件。不会加载直属文件！

types — 引入指定文件

typeRoots配置目录中所有包都会被默认引入，设置types则只会引入指定的包。

该例中，typeRoots指定了declaration和 node_module/@types ，types只引入global未引入declaration中的 global包。因此只有global包有效，而global_other未能生效。由上图可证。

其他

其他一些compilerOptions配置可参考typescript的tsconfig官方文档。下面是从网上找的一些配置说明，另补了自己的一些实践笔记可做参考。

{
/* 基本选项 */
"target": "es5",                       // 指定 ECMAScript 目标版本: es3、es5、es6/es2015、es2016、es2017、es2018、es2019、es2020、es2021、es2022、esnext
"module": "commonjs",                  // 指定使用模块: none、commonjs、amd、umd、system、es6/es2015、es2020、es2022、esnext、node16、nodenext
"lib": [],                             // 指定要包含在编译中的库文件
"allowJs": true,                       // 允许编译 javascript 文件
"checkJs": true,                       // 报告 javascript 文件中的错误
"jsx": "preserve",                     // 指定 jsx 代码的生成: 'preserve', 'react-native', or 'react'
"declaration": true,                   // 生成相应的 '.d.ts' 文件
"sourceMap": true,                     // 生成相应的 '.map' 文件
"outFile": "./",                       // 将输出文件合并为一个文件；只有module为amd或system才可用
"outDir": "./",                        // 指定输出目录
"rootDir": "./",                       // ts项目根目录，要包含所有源文件(不建议使用！)
"removeComments": true,                // 删除编译后的所有的注释
"noEmit": true,                        // 不生成输出文件
"importHelpers": true,                 // 从 tslib 导入辅助工具函数
"isolatedModules": true,               // 将每个文件做为单独的模块 （与 'ts.transpileModule' 类似）.

/* 严格的类型检查选项 */
"strict": true,                        // 启用所有严格类型检查选项；这个strict相关标志位的一个总开关, 设置为true会启用全部compilerOptions.strict开头的选项和其他相关的选项, 如strictNullChecks, strictPropertyInitialization, noImplicitAny ...;开启此选项后, 依然可以单独关闭某个具体的以compilerOptions.strict开头的选项
"noImplicitAny": true,                 // 在表达式和声明上有隐含的 any类型时报错
"strictNullChecks": true,              // 启用严格的 null 检查
"noImplicitThis": true,                // 当 this 表达式值为 any 类型的时候，生成一个错误
"alwaysStrict": true,                  // 以严格模式检查每个模块，并在每个文件里加入 'use strict'
"stricktPropertyInitialization": true, // 开启此选项让typescript严格的对象属性初始化检查;
  
/* 额外的检查 */
"noUnusedLocals": true,                // 有未使用的变量时，抛出错误
"noUnusedParameters": true,            // 有未使用的参数时，抛出错误
"noImplicitReturns": true,             // 并不是所有函数里的代码都有返回值时，抛出错误
"noFallthroughCasesInSwitch": true,    // 报告 switch 语句的 fallthrough 错误。（即，不允许 switch 的 case 语句贯穿）
"allowUnreachableCode": true,         // 是否允许存在永远无法被执行的代码， 当设置为false即不允许存在，eslint会提示错误并修复方法，而且tsc会报错;默认为undefined；配置为undefined时, 遇到这种情况会给出warning, 配置false则直接编译时抛出错误无法成功编译, 配置为true既没有警告也没有错误
 
/* 模块解析选项 */
"moduleResolution": "node",            // 选择模块解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)
"baseUrl": "./",                       // 用于解析非相对模块名称的基目录
"paths": {},                           // 模块名到基于 baseUrl 的路径映射的列表
"rootDirs": [],                        // 根文件夹列表，其组合内容表示项目运行时的结构内容
"typeRoots": [],                       // 包含类型声明的文件列表
"types": [],                           // 需要包含的类型声明文件名列表
"allowSyntheticDefaultImports": true,  // 允许从没有设置默认导出的模块中默认导入。

/* Source Map Options */
"sourceRoot": "./",                    // 指定调试器应该找到 TypeScript 文件而不是源文件的位置
"mapRoot": "./",                       // 指定调试器应该找到映射文件而不是生成文件的位置
"inlineSourceMap": true,               // 生成单个 soucemaps 文件，而不是将 sourcemaps 生成不同的文件
"inlineSources": true,                 // 将代码与 sourcemaps 生成到一个文件中，要求同时设置了 --inlineSourceMap 或 --sourceMap 属性

/* 其他选项 */
"experimentalDecorators": true,        // 启用装饰器
"emitDecoratorMetadata": true          // 为装饰器提供元数据的支持
}