<

ts-loader: Web包的TypeScript加载程序

( 如需查看英文版本，请 点击这里 )

Web包的TypeScript加载程序


ts-loader

这是webpack的TypeScript加载器。安装·报告错误·请求功能

目录

  • 开始安装运行示例更快地构建Yarn即插即用Babel并行化构建兼容性配置devtool/sourcemaps代码拆分和加载其他资源声明(.d.ts）失败的类型脚本编译错误baseUrl/paths模块解析选项加载程序选项transpileOnlyhappyPackMode resolveModuleName和resolveTypeReferenceDirective getCustomTransformers LogInfoToStOut logLevel静默忽略诊断报告文件编译器配置文件颜色错误格式化程序编译器选项实例附加后缀到AppendsxSuffix仅允许CompileBundledFiles上下文experimentalFileCaching项目引用使用webpack watch热模块更换
  • Contributing
  • License

Getting Started

Installation

yarn add ts-loader --dev

or

npm install ts-loader --save-dev

如果还没有安装TypeScript，还需要安装TypeScript。

yarn add typescript --dev

or

npm install typescript --save-dev

Running

像普通的一样使用webpack，包括webpack --watch和webpack-dev-server，或者通过另一个使用Node.jsAPI的构建系统来使用。

Examples

我们有许多示例设置来适应不同的工作流。我们的例子可以在这里找到。

我们可能有比我们需要的更多的例子。也就是说，这里有一个很好的开始方法：

  • 我要最简单的装置。使用“香草”ts-loader
  • 我想要最快的编译。使用fork-ts-checker-webpack-plugin。它在一个单独的进程中执行类型检查，ts-loader只处理透明操作。

Faster Builds

随着项目变得更大，编译时间线性增加。这是因为typescript的语义检查器必须在每次重建时检查所有文件。简单的解决方案是通过使用transpileOnly: true选项禁用它，但是这样做会使您没有类型检查，也不会输出声明文件。

您可能不想放弃类型检查；这是TypeScript的重点。所以您可以使用fork-ts-checker-webpack-plugin。它在一个单独的进程上运行类型检查器，因此由于transpileOnly: true，您的构建仍然很快，但是您仍然有类型检查。此外，该插件还进行了一些优化，以使增量类型检查更快（AST缓存，多个worker）。

如果你想看到一个简单的设置，看看我们的简单例子。对于更复杂的设置，请看我们更复杂的示例。

Yarn Plug’n’Play

ts-loader支持纱线即插即用。推荐的集成方法是使用pnp-webpack-plugin。

Babel

ts-loader与babel和babel-loader结合使用非常好。官方打字样本中就有这样一个例子。或者看看我们自己的例子。

Parallelising Builds

可以并行构建。从性能角度来看，这在webpack2/3中非常有用。与webpack4+相比，它的效益和成本似乎要少得多。

但是如果这是你想做的，有两种方法可以做到：happypack和thread-loader。两者都应与fork-ts-checker-webpack-plugin结合使用，表示typechecking.）

要了解更多信息，请查看webpack发布频道上的@johnny_reilly的这篇文章。

如果您想找到使用watchapi改进构建的进一步方法，那么可以看看@kenneth_chau的这篇文章。

Compatibility

  • TypeScript: 2.4.1+
  • webpack:4.x+（如果需要webpack2或3支持，请使用ts-loader3.x）
  • 节点：6.11.5最小值（与webpack 4对齐）

每晚都会运行一个完整的测试套件（以及每个pull请求）。它可以在Linux和Windows上运行，针对TypeScript的主要版本测试ts-loader。测试套件也运行在TypeScript@下一个（因为我们和你一样想使用它）。

如果您发现测试套件没有发现的问题，请让我们知道。更好的是，写一个测试，并提交一个公关！

Configuration

  1. 创建或更新webpack.config.js，如下所示：module.exports = { mode: "development", devtool: "inline-source-map", entry: "./app.ts", output: { filename: "bundle.js" }, resolve: { // Add `.ts` and `.tsx` as a resolvable extension. extensions: [".ts", ".tsx", ".js"] }, module: { rules: [ // all files with a `.ts` or `.tsx` extension will be handled by `ts-loader` { test: /\.tsx?$/, loader: "ts-loader" } ] } };
  2. 添加tsconfig.json文件。（下面的一个非常简单；但是你可以根据自己的心愿调整它）{ "compilerOptions": { "sourceMap": true } }

tsconfig.json文件控制TypeScript-related选项，以便您的IDE、tsc命令和此加载程序共享相同的选项。

devtool/源地图

如果您希望能够调试原始源代码，那么可以感谢sourcemaps的魔力。使用ts-loader和webpack设置此设置有两个步骤。

首先，ts-loader要生成源映射，需要将tsconfig.json选项设置为"sourceMap": true。

其次，需要在webpack.config.js中设置devtool选项，以支持所需的源映射类型。要做出选择，请阅读devtool网页包文档。你可能会被现有的选择吓坏了。您可能还需要根据您的构建环境来改变sourcemap策略。以下是一些不同的策略：

  • devtool: 'inline-source-map'-可靠的sourcemap支持；最好的"all-rounder"。与karma-webpack配合使用很好（不是所有的策略都可以）
  • devtool: 'cheap-module-eval-source-map'-调试时对sourcemaps的最佳支持。
  • devtool: 'source-map'-这种方法可以很好地处理UglifyJsPlugin；通常您可以在生产中使用这种方法

代码拆分和加载其他资源

加载css和其他资源是可能的，但是您需要确保您已经在声明文件中定义了require函数。

declare var require: {
  <T>(path: string): T;
  (paths: string[], callback: (...modules: any[]) => void): void;
  ensure: (
    paths: string[],
    callback: (require: <T>(path: string) => T) => void
  ) => void;
};

然后，您可以简单地为每个webpack文档要求资产或块。

require("!style!css!./style.css");

代码拆分需要相同的基本过程。在本例中，您需要import个模块，但不直接使用它们。相反，你需要他们在分裂点。有关详细信息，请参见此示例和此示例。

typescript2.4支持ECMAScript的新import()调用。这些调用导入一个模块并向该模块返回一个承诺。Web包中也支持此功能-有关使用的详细信息可在此处找到。代码拆分快乐！

Declarations (.d.ts)

要输出一个build.d.ts文件，可以在tsconfig中设置"declaration": true，并在webpack配置中使用DeclarationBundlerPlugin。

在TypeScript编译失败时发生错误

自webpack 2起，生成应因TypeScript编译错误而失败。如果由于某种原因它没有，您可以使用webpack-fail-plugin。

了解更多背景，请阅读本期文章。

baseUrl/paths模块分辨率

如果您想根据baseUrl和paths在tsconfig.json中解析模块，那么可以使用tsconfig-paths-webpack-plugin包。有关此功能的详细信息，请参阅模块解析文档。

此功能需要webpack 2.1+和TypeScript 2.0+。使用下面的配置或检查包以获取有关用法的更多信息。

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  ...
  resolve: {
    plugins: [new TsconfigPathsPlugin({ configFile: "./path/to/tsconfig.json" })]
  }
  ...
}

Options

有两种类型的选项：TypeScript选项（也称为“编译器选项”）和加载程序选项。TypeScript选项应该使用tsconfig.json文件设置。可以通过webpack配置中的options属性指定加载程序选项：

module.exports = {
  ...
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: [
          {
            loader: 'ts-loader',
            options: {
              transpileOnly: true
            }
          }
        ]
      }
    ]
  }
}

Loader Options

transpileOnly

Type Default Value
boolean false

如果要显著加快编译速度，可以设置此标志。但是，应用程序中不同依赖项之间的静态类型检查所带来的许多好处都将丢失。transpileOnly不会加快项目引用的编译速度。

建议在fork-ts-checker-webpack-plugin旁边使用transpileOnly来再次进行完整的类型检查。要想知道这在实践中是什么样的，那么可以看看我们的简单示例。对于更复杂的设置，请看我们更复杂的示例。

如果您启用此选项，每当您re-export一种类型时，webpack4将向您发出“export not found”警告：

WARNING in ./src/bar.ts
1:0-34 "export 'IFoo' was not found in './foo'
 @ ./src/bar.ts
 @ ./src/index.ts

发生这种情况的原因是，当typescript不执行完整的类型检查时，它没有足够的信息来确定导入的名称是否是类型，因此当导出名称时，typescript别无选择，只能发出导出。幸运的是，无关的导出不应该是有害的，因此您可以仅抑制以下警告：

module.exports = {
  ...
  stats: {
    warningsFilter: /export .* was not found in/
  }
}

happyPackMode

Type Default Value
boolean false

如果您正在使用HappyPack或thread-loader来并行构建，那么您需要将其设置为true。这会隐式地将*transpileOnly*设置为true并发出警告！停止将所有错误注册到Web包。

建议将其与fork-ts-checker-webpack-plugin一起使用，以便再次进行完整的类型检查。要想知道这在实践中是什么样子，那么可以看看我们简单的thread-loader示例。重要提示：如果您将fork-ts-checker-webpack-plugin与HappyPack或thread-loader一起使用，请确保将syntactic诊断选项设置为：

new ForkTsCheckerWebpackPlugin({
          typescript: {
            diagnosticOptions: {
              semantic: true,
              syntactic: true,
            },
          },
        })

这将确保插件检查语法错误（例如const array = [{} {}];）和语义错误（例如const x: number = '1';）。默认情况下，插件只检查语义错误（当在transpileOnly模式下与ts-loader一起使用时，ts-loader仍将报告语法错误）。

{71{71如果你也在使用@270模式的话，那就不要去看了。

resolveModuleName和resolveTypeReferenceDirective

这些选项应该是用于解析import语句和<reference types="...">指令的函数，而不是默认的TypeScript实现。这并不是为了让ts-loader的用户使用它们——它们的存在是为了促进诸如纱线即插即用之类的功能。

getCustomTransformers

Type
(program: Program) => { before?: TransformerFactory<SourceFile>[]; after?: TransformerFactory<SourceFile>[]; }

提供定制的转换器-仅与typescript2.3+兼容（如果使用transpileOnly模式，则为2.4）。例如，请查看typescript-plugin-styled-components或我们的测试。

您还可以传递一个路径字符串来定位js模块文件，该文件导出上述函数，这在happyPackMode中尤其有用。（因为分叉进程无法序列化函数请参阅相关问题的更多信息）

logInfoToStdOut

Type Default Value
boolean false

如果您从stdout或stderr读取，这对于正确的错误处理非常重要。默认值确保您可以通过管道读取stdout，或者使用webpack-j生成json输出。

logLevel

Type Default Value
string warn

可以是info、warn或error，这将日志输出限制为指定的日志级别。请注意这样一个事实：错误被写入stderr，而其他所有内容都写入stderr（如果logInfoToStdOut为true，则为stdout）。

silent

Type Default Value
boolean false

如果true，则不会发出console.log消息。请注意，大多数错误消息是通过不受此标志影响的webpack发出的。

ignoreDiagnostics

Type Default Value
number[] []

通过指定要忽略的诊断代码数组，可以消除某些类型脚本错误。

reportFiles

Type Default Value
string[] []

仅报告与全局模式匹配的文件。

// in webpack.config.js
  {
    test: /\.ts$/,
    loader: 'ts-loader',
    options: { reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts'] }
  }

当某些类型定义中存在对应用程序不致命的错误时，这将非常有用。

compiler

Type Default Value
string 'typescript'

允许使用正式类型脚本编译器以外的其他类型脚本编译器。应该设置为编译器的NPM名称，例如ntypescript。

configFile

Type Default Value
string 'tsconfig.json'

允许您指定在何处查找TypeScript配置文件。

你可以提供

  • 只是一个文件名。然后，加载程序将在各个入口点的包含文件夹中搜索每个入口点的配置文件。如果在那里找不到配置文件，它将沿着父目录链向上移动，并在这些文件夹中查找配置文件。
  • 配置文件的相对路径。它将相对于相应的.ts条目文件进行解析。
  • 配置文件的绝对路径。

请注意，如果配置文件在项目目录之外，则可能需要设置context选项以避免类型脚本问题（如TS18003）。在本例中，configFile应该指向tsconfig.json，而context指向项目根。

colors

Type Default Value
boolean true

如果false，则禁用记录器消息中的built-in颜色。

errorFormatter

Type Default Value
(message: ErrorInfo, colors: boolean) => string undefined

默认情况下，ts-loader将TypeScript编译器输出格式化为以下样式的错误或警告：

[tsl] ERROR in myFile.ts(3,14)
      TS4711: you did something very wrong

如果这种格式不符合您的口味，您可以使用下面的errorFormatteroption.提供您自己的格式化程序，这是一个自定义错误格式化程序的模板。请注意，colors参数是chalk的一个实例，您可以使用它来为输出着色。（此实例将考虑colorsoption.）

function customErrorFormatter(error, colors) {
  const messageColor =
    error.severity === "warning" ? colors.bold.yellow : colors.bold.red;
  return (
    "Does not compute.... " +
    messageColor(Object.keys(error).map(key => `${key}: ${error[key]}`))
  );
}

如果上述格式化程序收到如下错误：

{
  "code":2307,
  "severity": "error",
  "content": "Cannot find module 'components/myComponent2'.",
  "file":"/.test/errorFormatter/app.ts",
  "line":2,
  "character":31
}

它将产生一条错误消息，说明：

Does not compute.... code: 2307,severity: error,content: Cannot find module 'components/myComponent2'.,file: /.test/errorFormatter/app.ts,line: 2,character: 31

“不计算…”后面的位会是红色的。

compilerOptions

Type Default Value
object {}

允许重写TypeScript选项。应使用与中compilerOptions属性相同的格式指定tsconfig.json文件.

instance

Type Default Value
string TODO

强制文件通过TypeScript编译器的不同实例的高级选项。可用于在代码的不同部分之间强制隔离。

appendTsSuffixTo

Type Default Value
`(RegExp string)[]`

appendTsxSuffixTo

Type Default Value
`(RegExp string)[]`

要与filename匹配的正则表达式的列表。如果文件名与其中一个正则表达式匹配，则在该文件名后会附加一个.ts或.tsx后缀。如果使用HappyPack或thread-loader和ts-loader，则需要对正则表达式使用string类型，而不是RegExp对象。

// change this:
{ appendTsSuffixTo: [/\.vue$/] }
// to:
{ appendTsSuffixTo: ['\\.vue$'] }

现在这对于*.vue文件格式很有用。（可能会受益于future.中新的单文件格式）

Example:

webpack.config.js:

module.exports = {
  entry: "./index.vue",
  output: { filename: "bundle.js" },
  resolve: {
    extensions: [".ts", ".vue"]
  },
  module: {
    rules: [
      { test: /\.vue$/, loader: "vue-loader" },
      {
        test: /\.ts$/,
        loader: "ts-loader",
        options: { appendTsSuffixTo: [/\.vue$/] }
      }
    ]
  }
};

index.vue

<template><p>hello {{msg}}</p></template>
<script lang="ts">
export default {
data(): Object {
return {
msg: "world"
};
}
};
</script>

我们可以用类似的方法处理.tsx：

webpack.config.js:

module.exports = {
    entry: './index.vue',
    output: { filename: 'bundle.js' },
    resolve: {
        extensions: ['.ts', '.tsx', '.vue', '.vuex']
    },
    module: {
        rules: [
            { test: /\.vue$/, loader: 'vue-loader',
              options: {
                loaders: {
                  ts: 'ts-loader',
                  tsx: 'babel-loader!ts-loader',
                }
              }
            },
            { test: /\.ts$/, loader: 'ts-loader', options: { appendTsSuffixTo: [/TS\.vue$/] } }
            { test: /\.tsx$/, loader: 'babel-loader!ts-loader', options: { appendTsxSuffixTo: [/TSX\.vue$/] } }
        ]
    }
}

tsconfig.json（将jsx选项设置为preserve，让巴贝尔处理jsx）

{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

index.vue

<script lang="tsx">
export default {
functional: true,
render(h, c) {
return (<div>Content</div>);
}
}
</script>

或者，如果只想使用tsx，只需使用appendTsxSuffixTo选项：

{ test: /\.ts$/, loader: 'ts-loader' }
            { test: /\.tsx$/, loader: 'babel-loader!ts-loader', options: { appendTsxSuffixTo: [/\.vue$/] } }

onlyCompileBundledFiles

Type Default Value
boolean false

ts-loader的默认行为是作为tsc命令的drop-in替换，因此它尊重include、files和exclude选项，加载这些选项指定的任何文件。onlyCompileBundledFiles选项修改此行为，只加载由webpack实际绑定的那些文件，以及tsconfig.json设置包含的任何.d.ts文件。.d.ts文件仍然包含在其中，因为编译时可能需要这些文件而没有显式导入，因此不会被webpack获取。

allowTsInNodeModules

Type Default Value
boolean false

默认情况下，ts-loader不会编译node_modules中的.ts文件。您不需要在那里重新编译.ts文件，但是如果您真的想重新编译，请使用此选项。请注意，此选项充当白名单-您希望导入的任何模块都必须包含在项目的tsconfig.json的"files"或"include"块中。

See: https://github.com/Microsoft/TypeScript/issues/12358

// in webpack.config.js
  {
    test: /\.ts$/,
    loader: 'ts-loader',
    options: { allowTsInNodeModules: true }
  }

在你的tsconfig.json中：

{
    "include": [
      "node_modules/whitelisted_module.ts"
    ],
    "files": [
      "node_modules/my_module/whitelisted_file.ts"
    ]
  }

context

Type Default Value
string undefined

如果设置，将解析以给定绝对路径作为基路径的TypeScript配置文件。默认情况下，配置文件的目录用作基本路径。解析时，配置文件中的相对路径相对于基路径进行解析。选项context允许将选项configFile设置为项目根目录以外的路径（例如NPM包），而ts-loader的基本路径可以保持为项目根目录。

请记住，项目根目录中没有tsconfig.json可能会导致ts-loader和tsc之间的不同行为。当使用VS Code这样的编辑器时，建议将tsconfig.json文件添加到项目的根目录，并扩展选项configFile中引用的配置文件。欲了解更多信息，请阅读作为基础的公关，并阅读促成此选项的公关。

webpack:

{
  loader: require.resolve('ts-loader'),
  options: {
    context: __dirname,
    configFile: require.resolve('ts-config-react-app')
  }
}

Extending tsconfig.json:

{ "extends": "./node_modules/ts-config-react-app/index" }

注意，ts-loader不考虑扩展文件中的更改。它的目的是满足代码编辑器的要求。

experimentalFileCaching

Type Default Value
boolean true

默认情况下，每当TypeScript编译器需要检查文件/目录是否存在或解析符号链接时，它都会进行系统调用。它不缓存这些操作的结果，这可能会导致许多具有相同参数的系统调用（请参见示例注释）。在某些情况下，它可能会导致性能下降。

此标志为一些FS-functions启用缓存，如TypeScript编译器的fileExists、realpath和directoryExists。请注意，缓存在编译之间被清除。

projectReferences

Type Default Value
boolean false

ts-loader对项目引用具有opt-in支持。启用此配置选项后，ts-loader将以与tsc --build相同的方式增量重建上游项目。否则，被引用项目中的源文件将被视为根项目的一部分。

使用webpack watch

因为TS会生成.js和.d.TS文件，所以应该忽略这些文件，否则观察者可能会进入一个无限的监视循环。例如，在使用webpack时，您可能希望将其添加到webpack.conf.js文件中：

plugins: [
   new webpack.WatchIgnorePlugin([
     /\.js$/,
     /\.d\.ts$/
   ])
 ],

值得注意的是，使用LoaderOptionsPlugin仅仅是权宜之计。您可能需要考虑将其完全删除。

热模块更换

我们不支持HMR，因为我们还没有找到一个可靠的方法来建立它。

如果您想尝试一下webpack-dev-serverHMR，请遵循官方的webpack HMR指南，然后为ts-loader调整几个配置选项：

  1. 将transpileOnly设置为true（请参阅transpileOnly了解上面的配置详细信息和建议）。
  2. 在HMR acceptance回调函数中，可能是re-require被替换的模块。

Contributing

这是你的打字机！我们希望你能帮我们做得更好。请随意投稿；请参阅投稿人指南开始。

License

MIT License