拓冰网站定制 
Create React App 添加 TypeScript 完整指南模板创建、渐进迁移与类型检查链路解析【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app本篇指南聚焦于在 Create React AppCRA项目中引入 TypeScript 的两条路径使用官方typescript模板创建全新项目以及为现有项目渐进式添加 TypeScript 支持。文中将结合本仓库中react-scripts的源码实现如 tsconfig 自动生成逻辑、webpack 类型检查插件接入展开讲解读完你可以独立完成 TypeScript 项目的初始化、存量项目迁移并理解 CRA 底层是如何校验和兜底你的 TypeScript 配置的。功能可用性与前置说明在开始之前需要明确本文所述特性自react-scripts2.1.0及更高版本起可用。TypeScript 是 JavaScript 的类型化超集最终会被编译为普通 JavaScript 运行因此你可以在享受静态类型检查的同时保持浏览器端零额外运行时负担。另外从 CRA 4 时代起全局安装的create-react-app不再受支持。如果你此前通过npm install -g create-react-app安装过全局版本建议先卸载以确保npx始终拉取最新版本npm uninstall -g create-react-app # 或 yarn global remove create-react-app这一要求在 packages/create-react-app/createReactApp.js 的 CLI 提示中也有对应体现——当项目创建流程因缺少模板中断时CLI 会直接建议用户卸载全局包后重试。方式一用官方 TypeScript 模板创建全新项目创建带 TypeScript 的 CRA 项目最简单的方式是在创建命令后追加--template typescriptnpx create-react-app my-app --template typescript使用 Yarn 时等价命令为yarn create react-app my-app --template typescript--template参数的使用规则与自定义模板一致模板在 npm 上的命名格式为cra-template-[template-name]但命令中只需提供[template-name]部分。CRA 的 CLI 在 createReactApp.js 中会解析该参数并解析对应的模板包例如cra-template-typescript。模板来源不限于 npm 官方包也可以是本地相对路径、.tgz或.tar.gz归档详见 自定义模板文档。官方 TypeScript 模板包含什么本仓库中的 cra-template-typescript 就是官方提供的 TypeScript 基础模板。创建项目时init.js 会把template目录下的文件拷贝到项目根目录并按 template.json 中声明的package.dependencies安装额外依赖随后移除模板包本身。模板文件结构src目录下包括index.tsx应用入口使用createRoot挂载 React 应用App.tsx根组件App.test.tsx配套测试用例reportWebVitals.ts性能指标上报入口setupTests.ts测试环境初始化index.css/App.css样式文件模板声明的核心依赖见 template.json包括依赖说明typescriptTypeScript 编译器本体types/react/types/react-domReact 与 React DOM 的类型声明types/nodeNode 环境类型声明覆盖process、path等types/jestJest 测试框架类型声明testing-library/react等测试工具链同时模板在eslintConfig中声明extends: [react-app, react-app/jest]使 ESLint 规则与 TypeScript 解析器配置开箱即用。项目创建成功后npm start/npm test/npm run build等脚本的行为与普通 CRA 项目一致详见 可用脚本文档区别仅在于源码文件扩展名为.tsx/.ts且构建过程中多了类型检查环节。方式二为现有 CRA 项目渐进添加 TypeScript对于已经存在的 JavaScript 项目可以按以下步骤逐步引入 TypeScript而不必重新创建项目。第一步安装 TypeScript 与类型声明在项目根目录执行npm install --save typescript types/node types/react types/react-dom types/jest使用 Yarn 时yarn add typescript types/node types/react types/react-dom types/jest各类型声明包的用途与上文模板依赖一致types/react与types/react-dom提供 React 组件、Hooks、事件对象等 API 的类型types/node覆盖 Node 全局对象与模块types/jest让测试文件中的describe、it、expect等全局函数具备类型。若你使用了其他第三方库如react-router、axios通常还需要额外安装对应的types/*包或确认库自带类型声明。第二步将源文件重命名为 TypeScript 文件把入口文件src/index.js重命名为src/index.tsx。只要文件内含 JSX 语法扩展名就必须是.tsx纯逻辑文件可以使用.ts。重命名后React 组件、工具函数可以按需逐个迁移未迁移的.js文件在allowJs开启的情况下可以继续共存从而实现渐进式改造。第三步确保项目根目录存在 tsconfig.json重命名文件后检查项目根目录是否存在tsconfig.json。如果不存在CRA 会在你下次运行开发服务器时自动为你生成一份详见下文tsconfig.json 自动生成机制一节当然你也可以参照 TypeScript 官方 tsconfig 文档 手动创建。官方推荐直接编辑自动生成的配置因为 CRA 会保留你的自定义项只对缺失或冲突的选项进行修正。第四步重启开发服务器最后务必重启你的开发服务器npm start。这是因为 webpack 的解析规则、类型检查插件是否启用都取决于项目启动时tsconfig.json是否存在见下文源码分析单纯热重载不会触发配置重新加载。重启后类型错误会与构建日志一同显示在同一个终端控制台中。你需要先修复这些类型错误才能继续开发或执行生产构建——这正是 TypeScript 带来的强约束类型安全是编译前的硬门槛。tsconfig.json 自动生成机制与默认值解析很多开发者好奇 CRA 到底往tsconfig.json里写了什么。答案在 verifyTypeScriptSetup.js 中该脚本由 init.js 在模板安装完成后检测到安装依赖中包含typescript时调用用于初始化 TypeScript 配置。自动生成的时机verifyTypeScriptSetup的核心逻辑如下verifyTypeScriptSetup.js若项目根目录不存在tsconfig.json且src下检测到.ts/.tsx文件则先写入一个空对象{}占位标记为首次初始化若src下没有任何 TypeScript 文件则直接返回不做任何处理若tsconfig.json已存在则读取并校验其内容。随后脚本会解析当前 tsconfig包括extends继承逐项核对compilerOptions把缺失的建议值补进去、把与 webpack 配置冲突的必填值强制修正最后将结果写回文件并在终端打印变更说明。建议值suggested可自由修改以下选项在用户未显式配置时会被自动写入你可以随意修改它们选项默认建议值说明targetes5编译目标保证产物在旧浏览器上的兼容性lib[dom, dom.iterable, esnext]引入的库类型声明allowJstrue允许混用.js文件是渐进迁移的关键skipLibChecktrue跳过声明文件.d.ts的类型检查加快编译esModuleInteroptrue允许import React from react这种默认导入写法allowSyntheticDefaultImportstrue配合esModuleInterop处理无默认导出的模块stricttrue开启严格模式含strictNullChecks等forceConsistentCasingInFileNamestrue强制文件路径大小写一致避免跨平台问题noFallthroughCasesInSwitchtrue禁止 switch 分支意外穿透必填值required不可更改以下选项由 CRA 强制固定若用户配置了不同值脚本会直接覆盖并打印原因因为它们必须与 webpack 的解析行为保持一致选项强制值原因源码注释moduleesnext支持import()动态导入与import/export语法moduleResolutionnode与 webpack 的模块解析方式对齐resolveJsonModuletrue匹配 webpack 的 JSON loaderisolatedModulestrueBabel 单文件转译的实现限制noEmittrue类型检查不产出文件编译交给 Babeljsxreact-jsxReact 17 且 TS ≥ 4.1或react支持 React 17 的新 JSX transform旧环境回退到经典模式paths不设置别名导入不受支持webpack.config.js 中同样注释了 aliased imports 不可用include 与类型引用文件除compilerOptions外脚本还会确保include至少包含srcverifyTypeScriptSetup.js。此外它会检查src/react-app-env.d.ts是否存在若不存在则写入一行/// reference typesreact-scripts /。该声明文件是连接 CRA 内置类型如import.meta.env、静态资源模块声明、process.env.REACT_APP_*与你的项目的桥梁删除它会导致部分类型丢失。构建链路中的类型检查ForkTsCheckerWebpackPlugin 与 TSC_COMPILE_ON_ERRORwebpack 配置中CRA 通过fs.existsSync(paths.appTsConfig)判断项目是否启用了 TypeScriptwebpack.config.js从而决定是否在 resolve 规则中加入.ts/.tsx扩展名解析是否挂载 TypeScript 类型检查插件。类型检查由ForkTsCheckerWebpackPlugin承担webpack.config.js。该插件在独立进程中运行完整的 TypeScript 类型检查避免阻塞 webpack 主线程的编译这也是为什么类型错误与构建错误会同时出现在同一控制台、但互不阻塞的原因。开发模式下插件以异步async方式运行不会阻碍模块热更新。值得特别说明的是 TSC_COMPILE_ON_ERROR 环境变量在 advanced-configuration.md 中有完整的环境变量清单。当设置TSC_COMPILE_ON_ERRORtrue时webpack 会改用 ForkTsCheckerWarningWebpackPlugin将类型错误降级为警告见 webpack.config.js 的插件选择逻辑即使存在类型错误你也能照常运行和构建 TypeScript 项目错误会以警告形式打印在终端和浏览器控制台中方便你边开发边修复。也就是说默认情况下类型错误是阻断式的必须修复才能继续而TSC_COMPILE_ON_ERRORtrue提供了一条容忍式的通道适合在大型存量项目迁移初期使用。常见问题排查Troubleshooting创建出的项目没有启用 TypeScript如果执行--template typescript后项目仍是纯 JavaScript很可能是npx使用了缓存的旧版create-react-app。解决办法同样是卸载全局版本npm uninstall -g create-react-app # 或 yarn global remove create-react-app然后在全新终端中重试创建命令确保npx拉取的是最新版本。从 create-react-app-typescript 迁移如果你正在使用社区旧的create-react-app-typescript脚手架需要先了解它与官方方案在 tsconfig 生成、类型检查接入方式上的差异再按官方模板的结构src下的.tsx入口、react-app-env.d.ts引用、模板依赖清单逐步对齐。官方在 CRA 3 时代起已将 TypeScript 支持内建无需任何第三方包。常量枚举const enum与命名空间namespace不受支持这是使用 Babel 编译 TypeScript 的固有约束。CRA 的转译链路是Babel 剥离类型 插件独立做类型检查而 Babel 的babel/plugin-transform-typescript对语法有若干限制其中就包括const enum不被支持普通enum可以namespace除声明合并等有限场景外不被支持部分装饰器语法、import 赋值等也不可用。如果代码中出现了这些语法编译会直接报错。规避方案是改用普通enum、模块化导出常量对象或使用as const断言等现代替代写法。这一限制同样作用于所有使用 Babel 转译 TypeScript 的构建体系并非 CRA 独有。进阶阅读环境变量与构建行为的高级配置advanced-configuration.md含TSC_COMPILE_ON_ERROR、DISABLE_NEW_JSX_TRANSFORM等与 TypeScript/JSX 相关的开关模板机制详解custom-templates.mdTypeScript 模板源码cra-template-typescript含 template.json 与 App.tsxtsconfig 自动生成与校验实现verifyTypeScriptSetup.js类型检查插件接入点webpack.config.js官方 TypeScript 基础文档TypeScript Handbook【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Create React App 添加 TypeScript 完整指南：模板创建、渐进迁移与类型检查链路解析
Create React App 添加 TypeScript 完整指南模板创建、渐进迁移与类型检查链路解析【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app本篇指南聚焦于在 Create React AppCRA项目中引入 TypeScript 的两条路径使用官方typescript模板创建全新项目以及为现有项目渐进式添加 TypeScript 支持。文中将结合本仓库中react-scripts的源码实现如 tsconfig 自动生成逻辑、webpack 类型检查插件接入展开讲解读完你可以独立完成 TypeScript 项目的初始化、存量项目迁移并理解 CRA 底层是如何校验和兜底你的 TypeScript 配置的。功能可用性与前置说明在开始之前需要明确本文所述特性自react-scripts2.1.0及更高版本起可用。TypeScript 是 JavaScript 的类型化超集最终会被编译为普通 JavaScript 运行因此你可以在享受静态类型检查的同时保持浏览器端零额外运行时负担。另外从 CRA 4 时代起全局安装的create-react-app不再受支持。如果你此前通过npm install -g create-react-app安装过全局版本建议先卸载以确保npx始终拉取最新版本npm uninstall -g create-react-app # 或 yarn global remove create-react-app这一要求在 packages/create-react-app/createReactApp.js 的 CLI 提示中也有对应体现——当项目创建流程因缺少模板中断时CLI 会直接建议用户卸载全局包后重试。方式一用官方 TypeScript 模板创建全新项目创建带 TypeScript 的 CRA 项目最简单的方式是在创建命令后追加--template typescriptnpx create-react-app my-app --template typescript使用 Yarn 时等价命令为yarn create react-app my-app --template typescript--template参数的使用规则与自定义模板一致模板在 npm 上的命名格式为cra-template-[template-name]但命令中只需提供[template-name]部分。CRA 的 CLI 在 createReactApp.js 中会解析该参数并解析对应的模板包例如cra-template-typescript。模板来源不限于 npm 官方包也可以是本地相对路径、.tgz或.tar.gz归档详见 自定义模板文档。官方 TypeScript 模板包含什么本仓库中的 cra-template-typescript 就是官方提供的 TypeScript 基础模板。创建项目时init.js 会把template目录下的文件拷贝到项目根目录并按 template.json 中声明的package.dependencies安装额外依赖随后移除模板包本身。模板文件结构src目录下包括index.tsx应用入口使用createRoot挂载 React 应用App.tsx根组件App.test.tsx配套测试用例reportWebVitals.ts性能指标上报入口setupTests.ts测试环境初始化index.css/App.css样式文件模板声明的核心依赖见 template.json包括依赖说明typescriptTypeScript 编译器本体types/react/types/react-domReact 与 React DOM 的类型声明types/nodeNode 环境类型声明覆盖process、path等types/jestJest 测试框架类型声明testing-library/react等测试工具链同时模板在eslintConfig中声明extends: [react-app, react-app/jest]使 ESLint 规则与 TypeScript 解析器配置开箱即用。项目创建成功后npm start/npm test/npm run build等脚本的行为与普通 CRA 项目一致详见 可用脚本文档区别仅在于源码文件扩展名为.tsx/.ts且构建过程中多了类型检查环节。方式二为现有 CRA 项目渐进添加 TypeScript对于已经存在的 JavaScript 项目可以按以下步骤逐步引入 TypeScript而不必重新创建项目。第一步安装 TypeScript 与类型声明在项目根目录执行npm install --save typescript types/node types/react types/react-dom types/jest使用 Yarn 时yarn add typescript types/node types/react types/react-dom types/jest各类型声明包的用途与上文模板依赖一致types/react与types/react-dom提供 React 组件、Hooks、事件对象等 API 的类型types/node覆盖 Node 全局对象与模块types/jest让测试文件中的describe、it、expect等全局函数具备类型。若你使用了其他第三方库如react-router、axios通常还需要额外安装对应的types/*包或确认库自带类型声明。第二步将源文件重命名为 TypeScript 文件把入口文件src/index.js重命名为src/index.tsx。只要文件内含 JSX 语法扩展名就必须是.tsx纯逻辑文件可以使用.ts。重命名后React 组件、工具函数可以按需逐个迁移未迁移的.js文件在allowJs开启的情况下可以继续共存从而实现渐进式改造。第三步确保项目根目录存在 tsconfig.json重命名文件后检查项目根目录是否存在tsconfig.json。如果不存在CRA 会在你下次运行开发服务器时自动为你生成一份详见下文tsconfig.json 自动生成机制一节当然你也可以参照 TypeScript 官方 tsconfig 文档 手动创建。官方推荐直接编辑自动生成的配置因为 CRA 会保留你的自定义项只对缺失或冲突的选项进行修正。第四步重启开发服务器最后务必重启你的开发服务器npm start。这是因为 webpack 的解析规则、类型检查插件是否启用都取决于项目启动时tsconfig.json是否存在见下文源码分析单纯热重载不会触发配置重新加载。重启后类型错误会与构建日志一同显示在同一个终端控制台中。你需要先修复这些类型错误才能继续开发或执行生产构建——这正是 TypeScript 带来的强约束类型安全是编译前的硬门槛。tsconfig.json 自动生成机制与默认值解析很多开发者好奇 CRA 到底往tsconfig.json里写了什么。答案在 verifyTypeScriptSetup.js 中该脚本由 init.js 在模板安装完成后检测到安装依赖中包含typescript时调用用于初始化 TypeScript 配置。自动生成的时机verifyTypeScriptSetup的核心逻辑如下verifyTypeScriptSetup.js若项目根目录不存在tsconfig.json且src下检测到.ts/.tsx文件则先写入一个空对象{}占位标记为首次初始化若src下没有任何 TypeScript 文件则直接返回不做任何处理若tsconfig.json已存在则读取并校验其内容。随后脚本会解析当前 tsconfig包括extends继承逐项核对compilerOptions把缺失的建议值补进去、把与 webpack 配置冲突的必填值强制修正最后将结果写回文件并在终端打印变更说明。建议值suggested可自由修改以下选项在用户未显式配置时会被自动写入你可以随意修改它们选项默认建议值说明targetes5编译目标保证产物在旧浏览器上的兼容性lib[dom, dom.iterable, esnext]引入的库类型声明allowJstrue允许混用.js文件是渐进迁移的关键skipLibChecktrue跳过声明文件.d.ts的类型检查加快编译esModuleInteroptrue允许import React from react这种默认导入写法allowSyntheticDefaultImportstrue配合esModuleInterop处理无默认导出的模块stricttrue开启严格模式含strictNullChecks等forceConsistentCasingInFileNamestrue强制文件路径大小写一致避免跨平台问题noFallthroughCasesInSwitchtrue禁止 switch 分支意外穿透必填值required不可更改以下选项由 CRA 强制固定若用户配置了不同值脚本会直接覆盖并打印原因因为它们必须与 webpack 的解析行为保持一致选项强制值原因源码注释moduleesnext支持import()动态导入与import/export语法moduleResolutionnode与 webpack 的模块解析方式对齐resolveJsonModuletrue匹配 webpack 的 JSON loaderisolatedModulestrueBabel 单文件转译的实现限制noEmittrue类型检查不产出文件编译交给 Babeljsxreact-jsxReact 17 且 TS ≥ 4.1或react支持 React 17 的新 JSX transform旧环境回退到经典模式paths不设置别名导入不受支持webpack.config.js 中同样注释了 aliased imports 不可用include 与类型引用文件除compilerOptions外脚本还会确保include至少包含srcverifyTypeScriptSetup.js。此外它会检查src/react-app-env.d.ts是否存在若不存在则写入一行/// reference typesreact-scripts /。该声明文件是连接 CRA 内置类型如import.meta.env、静态资源模块声明、process.env.REACT_APP_*与你的项目的桥梁删除它会导致部分类型丢失。构建链路中的类型检查ForkTsCheckerWebpackPlugin 与 TSC_COMPILE_ON_ERRORwebpack 配置中CRA 通过fs.existsSync(paths.appTsConfig)判断项目是否启用了 TypeScriptwebpack.config.js从而决定是否在 resolve 规则中加入.ts/.tsx扩展名解析是否挂载 TypeScript 类型检查插件。类型检查由ForkTsCheckerWebpackPlugin承担webpack.config.js。该插件在独立进程中运行完整的 TypeScript 类型检查避免阻塞 webpack 主线程的编译这也是为什么类型错误与构建错误会同时出现在同一控制台、但互不阻塞的原因。开发模式下插件以异步async方式运行不会阻碍模块热更新。值得特别说明的是 TSC_COMPILE_ON_ERROR 环境变量在 advanced-configuration.md 中有完整的环境变量清单。当设置TSC_COMPILE_ON_ERRORtrue时webpack 会改用 ForkTsCheckerWarningWebpackPlugin将类型错误降级为警告见 webpack.config.js 的插件选择逻辑即使存在类型错误你也能照常运行和构建 TypeScript 项目错误会以警告形式打印在终端和浏览器控制台中方便你边开发边修复。也就是说默认情况下类型错误是阻断式的必须修复才能继续而TSC_COMPILE_ON_ERRORtrue提供了一条容忍式的通道适合在大型存量项目迁移初期使用。常见问题排查Troubleshooting创建出的项目没有启用 TypeScript如果执行--template typescript后项目仍是纯 JavaScript很可能是npx使用了缓存的旧版create-react-app。解决办法同样是卸载全局版本npm uninstall -g create-react-app # 或 yarn global remove create-react-app然后在全新终端中重试创建命令确保npx拉取的是最新版本。从 create-react-app-typescript 迁移如果你正在使用社区旧的create-react-app-typescript脚手架需要先了解它与官方方案在 tsconfig 生成、类型检查接入方式上的差异再按官方模板的结构src下的.tsx入口、react-app-env.d.ts引用、模板依赖清单逐步对齐。官方在 CRA 3 时代起已将 TypeScript 支持内建无需任何第三方包。常量枚举const enum与命名空间namespace不受支持这是使用 Babel 编译 TypeScript 的固有约束。CRA 的转译链路是Babel 剥离类型 插件独立做类型检查而 Babel 的babel/plugin-transform-typescript对语法有若干限制其中就包括const enum不被支持普通enum可以namespace除声明合并等有限场景外不被支持部分装饰器语法、import 赋值等也不可用。如果代码中出现了这些语法编译会直接报错。规避方案是改用普通enum、模块化导出常量对象或使用as const断言等现代替代写法。这一限制同样作用于所有使用 Babel 转译 TypeScript 的构建体系并非 CRA 独有。进阶阅读环境变量与构建行为的高级配置advanced-configuration.md含TSC_COMPILE_ON_ERROR、DISABLE_NEW_JSX_TRANSFORM等与 TypeScript/JSX 相关的开关模板机制详解custom-templates.mdTypeScript 模板源码cra-template-typescript含 template.json 与 App.tsxtsconfig 自动生成与校验实现verifyTypeScriptSetup.js类型检查插件接入点webpack.config.js官方 TypeScript 基础文档TypeScript Handbook【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考