razzle-plugin-typescript 使用指南在 Razzle 项目中接入 ts-loader 与 ForkTsChecker 的完整方案【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址: https://gitcode.com/gh_mirrors/ra/razzle导读razzle-plugin-typescript是 Razzle 官方插件体系中的 TypeScript 集成方案它以ts-loader替换babel-loader负责.ts/.tsx的编译转译并在 Web 端构建中引入独立的fork-ts-checker-webpack-plugin进程执行类型检查。本文基于该插件在仓库中的实际实现index.js、单元测试tests/index.test.js以及官方示例工程examples/with-typescript-plugin系统讲解插件的安装、默认/自定义配置、每个选项的真实作用与底层行为并给出与 Razzle 内置 Babel TypeScript 支持的选型建议读完后你可以在自己的 Razzle 项目中按需接入或调优 TypeScript 编译管线。插件定位什么时候才需要它在开始配置之前需要先明确本插件的定位。razzle-plugin-typescript的 README 开篇就给出了一条重要结论Razzle 现已内置基于 Babel 的 TypeScript 支持。除非你确实有特殊需求否则推荐直接使用内置支持并参考 with-typescript 示例工程。也就是说Razzle 自身razzle包已经能够处理 TypeScriptrazzle/config/jest/...与构建管线默认支持.ts/.tsx的解析与编译见 with-typescript/README.md 中 Basic razzle will uses Babel to transform TypeScript to plain JavaScript 的说明。因此选择本插件的典型场景是希望用ts-loader做按文件粒度的转译而不是走 Babel 的语法剥离需要利用ts-loader的transpileOnly与experimentalWatchApi等选项优化 Webpack × TypeScript 的增量构建性能需要把eslint类型检查/代码风格检查集成进fork-ts-checker-webpack-plugin的独立进程中希望在 Babel 与 ts-loader 之间并存例如渐进式迁移 TypeScript 时仍让 Babel 处理.js文件、应用babel-plugin-styled-components等 Babel 转换对应useBabel: true。安装与最小配置安装依赖在 Razzle 项目中安装插件yarn add razzle-plugin-typescript根据 package.json插件运行时依赖fork-ts-checker-webpack-plugin^5.2.0、ts-loader^8.0.4与typescript4.0.3并对razzle、razzle-dev-utils均要求4.2.18以及webpack ~4||~5建立 peer 依赖。因此你的项目必须自行安装typescript与符合版本的webpack否则会在解析时失败。默认选项启用在项目根目录的razzle.config.js中声明插件// razzle.config.js module.exports { plugins: [typescript], };这是最简用法字符串typescript会被 Razzle 解析为对razzle-plugin-typescript的加载插件将使用全部默认选项。官方示例 examples/with-typescript-plugin/razzle.config.js 采用的就是这种写法。自定义选项启用当需要覆盖默认行为时将插件声明为对象形式通过options传入配置// razzle.config.js module.exports { plugins: [ { name: typescript, options: { useBabel: false, tsLoader: { transpileOnly: true, experimentalWatchApi: true, }, forkTsChecker: { eslint: { files: [*.js, *.jsx, *.ts, *.tsx], }, }, }, }, ], };name指定插件名options.pluginOptions即插件读取的配置对象——这一点从源码 index.js 中的opts.options.pluginOptions可以确认。全部选项详解含源码级默认值插件的全部配置由 index.js 中的defaultOptions定义用户传入的options会通过Object.assign与默认值进行浅合并。以下逐项说明。useBabel是否保留 Babel 处理 TypeScript类型boolean默认值false设为false默认时插件会从 webpack 规则中移除babel-loader源码 index.js只保留ts-loader处理.ts/.tsx同时会把babel-loader.exclude设置为/\.ts$/与/\.tsx$/index.js避免两者重复转译。设为true时ts-loader的use数组会变成[...babelLoader.use, ...tsLoader.use]index.js即先过 Babel 再过 ts-loader。适用于需要 Babel 与 TypeScript 之间的互操作JS/TS 混用需要对.tsx文件应用 Babel 插件例如babel-plugin-styled-components。该分支行为在测试 tests/index.test.js 中有明确断言useBabel: true时babel-loader保留且出现在.ts/.tsx的 loader 链中useBabel: false时babel-loader被移除。性能提示官方 with-typescript-plugin/README.md 特别提醒Babel 与 ts-loader 都会转译 ES6 代码双 loader 并存等于让 Razzle 做两遍工作在大型应用中会明显拖慢 HMR。若你是渐进式迁移可保留双 loader否则建议useBabel: false直接替换。tsLoaderts-loader 选项类型TSLoaderOptions默认值{ transpileOnly: true, experimentalWatchApi: true }该对象会透传给ts-loader源码中通过Object.assign({}, defaultOptions.tsLoader, options.tsLoader)合并见 index.js。可覆盖ts-loader支持的任何选项常用项包括选项默认值插件内作用transpileOnlytrue仅做转译、跳过类型检查把检查交给 ForkTsChecker换取更快的构建experimentalWatchApitrue开发模式下使用 TS 的增量 watch API加速增量编译happyPackMode继承 ts-loader 默认与transpileOnly配合用于多进程/线程化场景当transpileOnly: true时类型检查由下方forkTsChecker独立完成二者是配套关系。forkTsCheckerfork-ts-checker-webpack-plugin 选项类型TSCheckerOptions默认值来自 README 与源码结合{ async: compiler.options.mode development, typescript: true, eslint: { files: ./src/**/*.{ts,tsx,js,jsx}, }, issue: {}, formatter: codeframe, logger: { infrastructure: silent, issues: console, devServer: true, }, }该对象透传给fork-ts-checker-webpack-pluginindex.js。注意源码中的默认eslint.files为./src/**/*.{ts,tsx,js,jsx}index.jsREADME 示例中展示的是覆盖写法。常用的可覆盖项选项作用eslint.files指定参与 ESLint 检查的文件 globasync是否异步执行类型检查开发模式默认开启避免阻塞编译typescript是否启用 TypeScript 类型检查formatter问题输出格式默认codeframe带代码上下文logger日志通道配置infrastructure默认静默issues输出到 consoledevServer开启注意fork-ts-checker-webpack-plugin的eslint选项要求项目内配置好 ESLint如.eslintrc才能生效未配置时该项不产生实际检查。插件执行流程从配置到 Webpack插件通过暴露modifyWebpackConfig(opts)钩子参与构建index.js完整流程如下复制 webpack 配置并合并插件选项Object.assign默认值 用户值扩展resolve.extensions追加.ts、.tsx使 webpack 能解析 TS 模块定位 babel-loader 规则通过razzle-dev-utils的makeLoaderFinder(babel-loader)见 helpers.js找到 Razzle 内部配置中的 babel-loader若找不到则抛出明确错误index.js因为需要复用其include目录集合禁止 babel-loader 转译 TS 文件exclude: [/\.ts$/, /\.tsx$/]新增 ts-loader 规则test: /\.tsx?$/include继承 babel-loader 的include即 Razzle 默认的源码目录集合依据useBabel决定保留还是移除 babel-loader仅对 Web 端opts.env.target web注入 ForkTsCheckerWebpackPlugin服务端node target不注入避免重复类型检查开发模式下关闭config.output.pathinfo并设置removeAvailableModules: false、removeEmptyChunks: false、splitChunks: falseindex.js这几项优化来自微软 Outlook 团队的实践可显著提升 Webpack × TypeScript 增量构建性能。这些行为均有测试覆盖见 tests/index.test.js 中的三组用例——useBabelfalse扩展名、ts-loader 存在、ForkTsChecker 存在、babel-loader 移除、useBabeltruebabel-loader 保留并进入 ts-loader 链、服务端构建不注入 ForkTsChecker。配套工程化配置tsconfig 与 Jesttsconfig.json插件本身不生成tsconfig.json需要项目自行提供。官方示例 examples/with-typescript-plugin/tsconfig.json 采用 Microsoft TypeScript-React-Starter 风格的严格配置关键项包括jsx: react、esModuleInterop: true、moduleResolution: Node、strictNullChecks: true等并exclude掉node_modules、build、razzle.config.js等目录。Jest 对 TS 的适配Razzle 默认的 Jest 配置以 Babel 转译.js/.jsx要让测试识别.ts/.tsx需要在package.json中覆盖jest字段。官方示例examples/with-typescript-plugin/package.json的做法是引入ts-jest{ jest: { transform: { \\.(ts|tsx)$: ts-jest, \\.css$: rootDir/node_modules/razzle/config/jest/cssTransform.js, ^(?!.*\\.(js|jsx|css|json)$): rootDir/node_modules/razzle/config/jest/fileTransform.js }, testMatch: [ rootDir/src/**/__tests__/**/*.(ts|js)?(x), rootDir/src/**/?(*.)(spec|test).(ts|js)?(x) ], moduleFileExtensions: [ts, tsx, js, json], collectCoverageFrom: [src/**/*.{js,jsx,ts,tsx}] } }若你选择useBabel: true双 loader 方案则还应让.js/.jsx继续走 Babel 转换在transform中追加^.\\.(js|jsx)$: rootDir/node_modules/razzle/config/jest/babelTransform.js该建议来自 with-typescript-plugin/README.md与 Jest 默认规则对齐。与内置 Babel TypeScript 支持的选型对比维度Razzle 内置支持Babelrazzle-plugin-typescriptts-loader转译器Babel语法剥离ts-loader按文件编译类型检查需要额外配置Babel 默认不做类型检查ForkTsChecker 独立进程默认开启HMR 性能单 loader通常更快transpileOnly 开发模式优化项同样追求快Babel 插件作用于 TSX天然支持需useBabel: true适用场景大多数标准 TS 项目需要 ts-loader 行为、独立类型检查进程、ESLint 集成或渐进迁移选择建议与 README 立场一致默认优先用内置 Babel 支持参考 with-typescript 示例只有当你明确需要本插件提供的 ts-loader 管线、独立类型检查或自定义 fork-ts-checker 行为时再引入razzle-plugin-typescript参考 with-typescript-plugin 示例。参考链接插件 READMEpackages/razzle-plugin-typescript/README.md插件实现源码packages/razzle-plugin-typescript/index.jsloader 查找工具packages/razzle-plugin-typescript/helpers.js单元测试packages/razzle-plugin-typescript/tests/index.test.js插件依赖声明packages/razzle-plugin-typescript/package.json完整示例工程examples/with-typescript-plugin内置 Babel TS 支持示例examples/with-typescript【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址: https://gitcode.com/gh_mirrors/ra/razzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
