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

发布时间:2026/9/24 2:40:28

在 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),仅供参考
延伸阅读

更多相关文章

2026/9/24 2:40:28

我用豆包工作 Seed-2.1-pro,复刻了 QQ 时代爆红的魔术图片

大家好,我是 LucianaiB,最近一直在折腾 AI 图片。 前段时间,我又刷到了一样很有“童年杀”味道的东西:会变画面的闪卡。 小时候,文具店门口经常摆着这种卡片。拿在手里轻轻一转,人物、动作和光影就会跟着…

2026/9/24 3:45:31

AI陪伴机器人生产部署清单-从云服务器到稳定运行

10-生产部署清单-从云服务器到稳定运行系列:AI 伙伴(AI-Partner)——具身智能陪伴机器人 数据接口部署与二次开发篇(10/12)一、先说结论:这套 Demo 距离生产差几步 AI 伙伴(AI-Partner&#xf…

2026/9/24 3:45:31

AutoCAD硬件加速与显卡驱动优化指南

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/24 3:45:31

陪诊行业爆发:平台 + 陪诊师 + 医院 + 渠道多方分账怎么解?

随着老龄化加剧、优质医疗资源紧张和城市就医流程复杂化,陪诊服务正在从 “小众帮忙” 变成城市家庭的高频刚需。一线城市陪诊平台数量已超过 200 家,不少项目从医院周边的小团队,快速成长为连接患者、陪诊师、医院渠道、保险公司和推荐人的医…

2026/9/23 12:07:00

GAMP 5 基于风险的计算机化系统验证:软件分类与审计追踪实践

简介:《A Risk-Based Approach to Compliant GxP Computerized Systems》即业内熟知的GAMP 5指南,面向制药企业质量与IT合规人员、验证工程师及计算机化系统管理者,用于解决GxP法规环境下系统合规性难以科学落地的问题。文档以风险管理为主线…

2026/9/23 12:06:55

安全托管MSSP实战:从静态防御到人机协同的攻防运营与应急响应

简介:这份PPT围绕互联网业务安全托管服务展开,面向企业安全负责人、IT运维人员及关注MSSP/MSS选型的读者,重点回应传统安全过度依赖人工、碎片化静态防御难以对抗产业化攻击等痛点。资源共1个pptx文件,包体约30.63MB,以…

2026/9/24 0:00:21

基于YOLOv8的渔船作业监控系统:从环境搭建到边缘部署全流程

简介:这是一套面向计算机、人工智能、自动化等专业学生与教师的毕业设计级项目资源,围绕YOLOv8实现渔船作业监控系统,可用于毕设、课程设计、大作业或项目立项演示。压缩包共97个文件,约24.21MB,以70个Python源码文件为…

2026/9/24 0:00:21

单细胞注释实战:基于Scanpy的标记基因与参考映射流程解析

简介:一份基于单细胞RNA测序数据的细胞类型注释算法研究Python毕业设计源码,针对计算机相关专业正在做毕设或需要项目实战的学习者,可用于课程设计与期末大作业。项目代码完整、经导师指导评审通过,可直接运行,覆盖数据…

2026/9/24 0:00:21

C#源生成器实战:用增量生成器替代反射,告别AOT崩溃

第一次在项目里被反射卡住,是在一个老旧的WinForms模块里:几十个类依赖PropertyChanged通知,运行时反射读属性、发通知,每次启动慢半拍不说,一上.NET Native/AOT裁剪模式几乎全面崩盘。后来我把这段逻辑全部改成C#源生…

2026/9/22 16:34:32

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/22 20:01:30

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/22 13:25:41

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码