在 Razzle 中使用 TypeScript：razzle-plugin-typescript 插件与 ts-loader 配置实战

前端构建工具前端构建后端【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址https://gitcode.com/gh_mirrors/ra/razzle点击查看免费下载本指南基于 Razzle 官方示例项目 with-typescript-plugin 及其配套插件源码 razzle-plugin-typescript系统讲解如何在零配置的 Razzle 通用渲染应用中接入 TypeScript。读完本文你将掌握两种 TypeScript 接入路径内置 Babel 支持与 ts-loader 插件方案的取舍、插件三个核心配置项useBabel、tsLoader、forkTsChecker的语义与底层实现以及如何改造 Jest 配置让 TS/TSX 测试与快照覆盖率正常工作。为什么需要专门的 TypeScript 插件Razzle 的核心承诺是零配置创建服务端渲染的通用 JavaScript 应用它的默认工具链基于 Babel。因此 Razzle 本身就已内置了通过 Babel 处理 TypeScript 的能力babel/preset-typescript一类预设负责剥离类型注解。那么razzle-plugin-typescript存在的意义是什么从插件 README见 packages/razzle-plugin-typescript/README.md可以明确读到Razzle 现已内置对 TypeScript 的 Babel 支持除非有特殊需求官方推荐直接使用内置支持即 with-typescript 示例的用法。本插件的价值在于当你需要ts-loader这类类型检查 转译一体的编译路径而不是仅做类型擦除时用它把 webpack 中的babel-loader替换为ts-loader。两种方案的差异用官方示例文档examples/with-typescript-plugin/README.md中的原话来说Babel 和 TypeScript 都能转译 ES6 代码如果同时跑两个 loader等于让 Razzle 做两遍工作在大应用上会显著拖慢 HMR。因此该示例采用用ts-loader覆盖babel-loader的单 loader 策略。快速开始创建并运行示例官方示例可以直接用脚手架一键拉取。在 examples/with-typescript-plugin/README.md 中给出的命令如下npx create-razzle-app --example with-typescript-plugin with-typescript-plugin cd with-typescript-plugin yarn start启动后默认监听3000端口服务端入口见 src/index.tsPORT环境变量可覆盖默认端口。除start外package.json 还提供了完整的生命周期脚本{ scripts: { start: razzle start, build: razzle build, test: razzle test --envjsdom, start:prod: NODE_ENVproduction node build/server.js } }razzle build产出build/目录其中build/server.js是可直接用 Node 运行的服务端 bundlerazzle test基于 Jest配合--envjsdom让组件测试拥有 DOM 环境。示例的源码结构清晰体现了同构应用的代码组织方式src/index.ts服务端进程入口负责启动 Express 并挂载 HMR 热更新逻辑src/server.tsx服务端渲染逻辑使用renderToStringStaticRouter输出 HTML并通过RAZZLE_ASSETS_MANIFEST读取构建产物清单注入 CSS/JS 标签src/client.tsx浏览器端入口使用hydrateBrowserRouter完成水合src/App.tsx 与 src/Home.tsx路由组件src/App.test.tsx基于testing-library风格此处用react-dom的render编写的组件冒烟测试。插件的两种接入方式方式一默认配置推荐在 razzle.config.js 中整个配置只有一行use strict; module.exports { plugins: [typescript], };插件通过 Razzle 的插件系统按名称解析对应 npm 包razzle-plugin-typescript其modifyWebpackConfig钩子会自动完成下文所述的全部 webpack 改造。安装依赖时需确保 package.json 中的razzle-plugin-typescript、razzle、razzle-dev-utils版本一致并额外安装ts-loader、ts-jest、typescript等。方式二自定义 options来自 packages/razzle-plugin-typescript/README.md 的完整示例把每个可调项都显式写了出来// razzle.config.js module.exports { plugins: [ { name: typescript, options: { useBabel: false, tsLoader: { transpileOnly: true, experimentalWatchApi: true, }, forkTsChecker: { eslint: { files: [*.js, *.jsx, *.ts, *.tsx], } }, }, }, ], };配置项的语义与默认值结合 packages/razzle-plugin-typescript/index.js 源码中的defaultOptions三个配置项说明如下useBabel: boolean默认false是否在 TS 文件的编译链中保留 Babel。从源码 packages/razzle-plugin-typescript/index.js 可以看到其行为差异false默认不仅把babel-loader从 TS 文件上排除还会把 webpack 规则中所有babel-loader规则直接过滤掉TS/TSX 文件只走ts-loadertrue把babel-loader的use链排在ts-loader之前[...babelLoader.use, ...tsLoader.use]这样既保留 JS/TS 互操作也能让 Babel 插件如babel-plugin-styled-components作用于 TSX 文件。需要特别说明源码第 40 行babelLoader.exclude [/\.ts$/, /\.tsx$/]会在任何情况下先让babel-loader跳过 TS 文件——这是防止双份转译的关键防线。tsLoader: TSLoaderOptions默认{ transpileOnly: true, experimentalWatchApi: true }透传给ts-loader的选项。transpileOnly: true表示只做转译不做类型检查类型检查由fork-ts-checker-webpack-plugin在独立进程中承担见下文experimentalWatchApi: true启用ts-loader的实验性监听 API可显著加速开发期的增量编译。在 index.js 中插件会复用babel-loader的include字段即 Razzle 确定的待转译目录避免把node_modules等目录纳入 TS 编译范围。forkTsChecker: TSCheckerOptions默认启用类型检查 ESLint透传给fork-ts-checker-webpack-plugin的选项该插件把类型检查和 lint 放到独立进程执行避免阻塞 webpack 编译主流程。默认行为是async在开发模式下异步执行、typescript: true、formatter: codeframe且 index.js 默认对./src/**/*.{ts,tsx,js,jsx}开启 ESLint 检查。插件源码剖析它到底对 webpack 做了什么razzle-plugin-typescript的核心逻辑全部在 modifyWebpackConfig 钩子中共五步与官方示例 README 中手动改造 webpack的思路一一对应1. 扩展模块解析后缀config.resolve.extensions [...config.resolve.extensions, .ts, .tsx];让 webpack 在import时可以省略.ts/.tsx后缀解析模块。2. 定位babel-loader规则通过razzle-dev-utils的makeLoaderFinder(babel-loader)见 packages/razzle-plugin-typescript/helpers.js在 Razzle 内部 webpack 配置中安全地找到babel-loader。如果找不到会直接抛出错误index.js因为需要借用它的include来推导ts-loader的编译范围。3. 排除 TS 文件避免 Babel 重复转译babelLoader.exclude [/\.ts$/, /\.tsx$/];4. 注入ts-loader规则新增test: /\.tsx?$/的规则use为ts-loader并合并用户自定义选项index.js。5. 增加类型检查与开发期性能优化仅在客户端opts.env.target web构建中追加ForkTsCheckerWebpackPlugin开发模式下还会关闭output.pathinfo并精简optimizationremoveAvailableModules、removeEmptyChunks、splitChunks均置为false这些优化手段来自微软 Outlook 团队关于webpack × TypeScript 增量构建提速的实践经验源码注释见 index.js。也就是说插件方案与示例 README 中手动定位 babel-loader 并换装 ts-loader的做法在原理上完全等价插件只是把这个过程自动化、参数化并额外附赠了类型检查与开发期构建优化。手动改造方案不依赖插件官方示例文档 examples/with-typescript-plugin/README.md 也给出了不依赖插件的手动思路在razzle.config.js中通过modify钩子定位运行babel-loader的规则并换成ts-loader同时扩展.ts/.tsx解析后缀。这与插件内部实现完全一致适合希望完全掌控 webpack 配置的进阶用户。渐进迁移两种 loader 并存的情况文档特别强调了一个场景如果你是从 JS 项目渐进式迁移到 TypeScript可能希望babel-loader和ts-loader同时运行。此时必须避免 Babel 重复处理 TS 文件否则 Razzle 会做两遍转译大项目上 HMR 会非常慢。如果选择并存需要在 Jest 的transform中补充 JS 转译规则^.\\.(js|jsx)$: rootDir/node_modules/razzle/config/jest/babelTransform.js,这样.js/.jsx文件继续由 Babel 转换而.ts/.tsx交给ts-jest两者互不干扰。改造 Jest让 TS/TSX 测试跑起来TSX 组件测试依赖 Jest 的转换器配置。示例在 package.json 中通过jest字段覆盖了 Razzle 的默认 Jest 配置官方示例 README 中给出的是指向ts-jest/preprocessor.js的等价写法当前示例实际使用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} ] } }各字段的作用transform三类文件的转换器。ts-jest负责 TS/TSXCSS 和静态资源文件分别走 Razzle 提供的 cssTransform.js 与 fileTransform.js位于razzle/config/jest/下避免 Jest 因无法解析 CSS/图片而报错testMatch测试文件的匹配范围兼容__tests__目录与*.test.ts(x)/*.spec.ts(x)命名moduleFileExtensions将ts、tsx加入模块解析后缀使测试中的import ./App能解析到App.tsxcollectCoverageFrom覆盖率统计覆盖 JS/JSX/TS/TSX 全部源码。对应的 devDependencies 中需要出现ts-jest和types/jest见 package.json这是示例 README 明确提到的前提条件。TypeScript 编译器配置与资源声明tsconfig.json 要点tsconfig.json 沿用了微软官方 TypeScript-React-Starter 的配置风格示例 README 有明确说明关键项包括jsx: react编译 JSX 为React.createElementmodule: commonjs与 Node 端服务端渲染的运行环境匹配esModuleInterop: true与allowSyntheticDefaultImports: true支持import express from express这类默认导入写法src/server.tsx 中正是如此使用strictNullChecks: true、noImplicitAny: true等严格性开关保持开启但strict: false便于从 JS 渐进迁移exclude中排除了node_modules、build、razzle.config.js等无需类型检查的目录。资源模块的类型声明webpack 会处理 SVG 等静态资源但 TypeScript 不知道import ./react.svg是什么类型因此示例在 typings/index.d.ts 中声明了通配模块declare module *.svg { const content: any; export default content; }同时 tsconfig 的types: [typePatches, node, webpack-env]tsconfig.json确保这些补丁声明、Node 类型与 webpack 环境变量类型如module.hot、process.env.RAZZLE_ASSETS_MANIFEST在全局生效。总结与选型建议在 Razzle 项目中使用 TypeScript建议按以下原则决策常规新项目优先使用 Razzle 内置的 Babel 对 TypeScript 的支持参照 with-typescript 示例配置量最小需要独立类型检查或 Babel 插件作用于 TSX选择razzle-plugin-typescript它会在编译期通过ts-loaderfork-ts-checker-webpack-plugin提供类型检查与 ESLint并自动优化开发期构建性能正在从 JS 渐进迁移可让两种 loader 并存但务必配置好 Jest 的babelTransform规则并理解双 loader 意味着双倍转译开销的代价。无论走哪条路径Jest 的ts-jest转换器、moduleFileExtensions扩展与资源类型声明typings/index.d.ts都是让 TSX 代码在测试与构建链路上顺畅运行的必要配套这也是本示例项目最有参考价值的完整闭环配置。赞分享前端构建工具前端构建后端【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址https://gitcode.com/gh_mirrors/ra/razzle点击查看免费下载相关推荐Razzle 中集成 TypeScriptrazzle-plugin-typescript 插件完整配置与源码实现解析Razzle 中集成 TypeScriptrazzle plugin typescript 插件完整配置与源码实现解析 本篇技术指南围绕 Razzle 官方插前端构建工具前端构建后端razzle-plugin-typescript 使用指南在 Razzle 项目中接入 ts-loader 与 ForkTsChecker 的完整方案razzle plugin typescript 使用指南在 Razzle 项目中接入 ts loader 与 ForkTsChecker 的完整方案 导读前端构建工具前端构建后端在 Razzle 中使用 MDXrazzle-plugin-mdx 插件配置与源码解析在 Razzle 中使用 MDXrazzle plugin mdx 插件配置与源码解析 MDX 允许你在 Markdown 文档中直接书写 JSX 组件是构前端构建工具前端构建后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考