Nhost 仓库统一 TypeScript 配置体系基于 build/configs/tsconfig 的集中式 tsconfig 实践指南【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost 是一个开源的 Firebase 替代方案The Open Source Firebase Alternative with GraphQL其仓库是一个包含 Go 服务端、前端 Dashboard、文档站、落地页与多个 npm 包的多语言 monorepo。为了让散落在各处的 TypeScript 项目保持一致的编译与类型检查标准仓库在 build/configs/tsconfig 目录下维护了一套可被任意子项目通过extends继承的集中式 TypeScript 基础配置。本文将以该目录下的 README.md 与 build/configs/README.md 为骨架结合仓库内真实 JSON 配置与下游项目的实际继承方式完整讲解这套配置的文件组成、每一项编译选项的含义、各类项目如何选用与覆写以及如何在此基础上创建新项目。一、为什么需要集中式 tsconfig配置即标准在大型 monorepo 中TypeScript 配置最容易出现的问题是每个子项目一套配置、标准各说各话有人开了strict有人没开有人用 CommonJS有人用 ESM包名路径 alias 各写各的。最终结果是类型检查形同虚设跨项目协作成本急剧上升。build/configs/README.md 明确说明了这套集中式配置目录的三个核心收益一致性Consistency所有项目遵循同一套编译标准与最佳实践避免同一仓库内出现互相冲突的 tsconfig可维护性Maintainability配置变更只需在一处完成即可通过继承传播到所有下游项目无需逐个项目手工同步快速上手Onboarding新项目可以直接继承现成配置快速启动不必从零推敲每一项编译选项。这正是 monorepo 场景下配置即代码、配置即标准的典型实践标准定义在单一可信源single source of truth中子项目只保留真正属于自己的差异项。二、配置文件全景base / library / frontend / node / vitebuild/configs/tsconfig/README.md 列出的五份基础配置各自面向一类项目其依赖关系如下配置文件面向场景继承链base.json所有项目共用的核心设置无最底层library.json库与 SDK 包需要产出声明文件base.jsonfrontend.json前端应用React、Next.jsbase.jsonnode.jsonNode.js 应用与脚本base.jsonvite.jsonVite 配置文件vite.config.tsnode.json整个体系的顶层入口是 build/configs/README.md它负责说明有哪些配置、如何使用、如何新增而 build/configs/tsconfig/README.md 则深入每一份 JSON 的具体语义。下面逐份拆解。三、base.json所有项目的共同基线base.json 是整棵继承树的根定义了仓库内所有 TypeScript 项目都必须遵守的编译与类型检查基线。其核心配置可分为四组3.1 环境与特性Environment and Featureslib: [ESNext], target: ES2022, module: ESNext, moduleDetection: force, skipLibCheck: truetarget: ES2022输出目标为 ES2022可在现代 Node.js 与浏览器上直接利用原生 class 字段、Array.at、Object.hasOwn等新特性module: ESNextlib: [ESNext]使用最新的 ESM 模块语义与最新标准库类型配合现代打包器使用moduleDetection: force强制所有文件都按 ES 模块处理避免出现脚本文件与模块文件混用导致的隐式全局变量问题skipLibCheck: true跳过.d.ts声明文件的类型检查显著加快编译速度代价是声明文件中的错误不被检查这是多数大型项目的通行取舍。3.2 类型检查Type Checking——严格模式全家桶strict: true, noFallthroughCasesInSwitch: true, noImplicitOverride: true, noImplicitReturns: true, noUnusedLocals: true, noUnusedParameters: true, noUncheckedIndexedAccess: true, noPropertyAccessFromIndexSignature: true, allowUnusedLabels: false, allowUnreachableCode: false这一组是整个配置中含金量最高的部分远超出普通strict: true的基础要求strict: true一次性开启strictNullChecks、noImplicitAny、strictFunctionTypes、strictPropertyInitialization等全部严格检查noUncheckedIndexedAccess访问数组或索引签名时结果类型自动带上undefined强制开发者处理越界/缺键情况——这是 Nhost 前端代码大量使用可空判定的来源之一noPropertyAccessFromIndexSignature禁止用.语法访问索引签名属性必须写成obj[key]让来自索引签名的访问在代码层面显式化noImplicitOverride覆写基类方法时必须显式写override关键字防止因拼写错误静默产生新方法noImplicitReturns所有代码路径都必须显式返回杜绝漏 return 但类型上恰好兼容的隐性 bugnoUnusedLocals/noUnusedParameters未使用的局部变量与参数直接报错保证提交的代码干净无死代码allowUnreachableCode: false与allowUnusedLabels: false不可达代码与未使用标签一律视为错误。3.3 模块解析Module ResolutionesModuleInterop: true, resolveJsonModule: true, forceConsistentCasingInFileNames: trueesModuleInterop: true允许import React from react这类默认导入写法是处理 CJS 包与 ESM 语法互操作的关键开关resolveJsonModule: true可直接import data from ./data.jsonforceConsistentCasingInFileNames: true强制文件引用大小写一致避免在大小写不敏感文件系统上开发、部署到 Linux大小写敏感后报错的经典坑。3.4 高级选项Advanced OptionsverbatimModuleSyntax: true, isolatedModules: trueverbatimModuleSyntax: true类型导入必须写成import type { Foo }运行时导入与类型导入在语法层面被强制区分配合打包器可安全剔除类型代码isolatedModules: true保证每个文件可被独立转译符合 esbuild、Babel 等单文件转译器的要求防止跨文件类型依赖导致单文件转译出错。3.5 默认排除项exclude: [node_modules, **/dist, **/build]base.json统一排除了node_modules与产物目录子项目在继承时可根据自身需求追加排除规则。四、library.json面向库与 SDK 的产出配置library.json 面向需要对外发布、必须生成类型声明文件的库与 SDK 包Nhost 的 npm 包即是典型。它继承base.json后追加了产出相关配置declaration: true, declarationMap: true, sourceMap: true, outDir: ./dist, noEmit: false, composite: true, importHelpers: true, moduleResolution: node, types: [node], include: [src/**/*]declaration: truedeclarationMap: true生成.d.ts声明文件与声明源映射让使用方的编辑器可以跳转到 .ts 源码这是 SDK 体验的关键sourceMap: true同时输出.js.map便于调试发布后的代码outDir: ./dist统一产物目录noEmit: false明确允许输出base.json本身不设置noEmit此处显式声明语义composite: true开启工程引用Project References支持配合declaration使该包可被其他项目增量引用importHelpers: true将__awaiter等辅助函数收敛到tslib避免每个文件重复内联缩小包体积moduleResolution: node库包采用 Node 风格解析保证发布后在各类消费方环境中都能被正确解析types: [node]仅注入 Node 类型include: [src/**/*]exclude中的**/*.test.ts、**/*.spec.ts、**/__tests__/**编译范围限定在src且自动把测试文件排除在产物之外。仓库内的真实继承案例packages/nhost-js/tsconfig.json 继承library.json并追加了lib: [ESNext, DOM]、jsx: react-jsx与一组路径别名如nhost/nhost-js/auth→src/auth/index.ts、nhost/nhost-js/storage→src/storage/index.ts这些别名让 SDK 内部模块既能独立导入又保持对外一致packages/stripe-graphql-js/tsconfig.json 继承library.json仅以verbatimModuleSyntax: false和outDir: ./dist两处做最小化覆写——直观展示了继承 少量自定义的推荐姿势。五、frontend.json面向 React / Next.js 前端的配置frontend.json 面向浏览器前端React、Next.js 等同样继承base.jsonlib: [ESNext, DOM, DOM.Iterable], jsx: react-jsx, moduleResolution: bundler, allowImportingTsExtensions: true, noEmit: true, allowJs: true, allowSyntheticDefaultImports: true, incremental: true, plugins: [], include: [src/**/*, **/*.ts, **/*.tsx]lib: [ESNext, DOM, DOM.Iterable]在 base 的 ESNext 之上补入 DOM 与 DOM.Iterable 类型使document、NodeList迭代等浏览器 API 可用jsx: react-jsx使用 React 17 的自动 JSX 运行时无需在每个文件显式import ReactmoduleResolution: bundler面向 Vite、Webpack、Next.js 等打包器的新式解析策略允许无扩展名导入天然适配package.json的exports字段allowImportingTsExtensions: true允许import ./foo.ts这类带扩展名导入需要与noEmit搭配因为产物由打包器产出而非 tscnoEmit: true前端项目的类型检查交给打包器与 CItsc 只做校验不产出文件allowJs: true允许混入 JS 文件便于存量 JS 代码渐进迁移allowSyntheticDefaultImports: true配合esModuleInterop放宽 CJS 模块的默认导入incremental: true开启增量编译配合.tsbuildinfo缓存加速后续构建plugins: []预留空插件位注释说明Next.js 项目可在此注入 Next 插件非 Next.js 项目会自动忽略该项。仓库内的真实继承案例examples/guides/react-query/tsconfig.json 继承frontend.jsoninclude限定./src/**/*.ts(x)并通过references: [{ path: ./tsconfig.node.json }]关联配套的 Node 侧配置tsconfig.node.json则继承vite.json——这是 Vite 脚手架标准的双 tsconfig结构dashboard/tsconfig.json 未直接继承该文件而是自行声明了一套与frontend.json高度同构的选项strict、moduleResolution: bundler、jsx: react-jsx、noEmit、incremental等并追加了/*等路径别名与noImplicitAny: false、useUnknownInCatchVariables: false等定制项可作为集中配置演进过程中存量项目渐进对齐的参照。六、node.json面向 Node.js 应用与脚本node.json 面向 Node.js 服务端代码与工具脚本module: NodeNext, moduleResolution: NodeNext, target: ES2022, lib: [ESNext], sourceMap: true, types: [node], allowJs: true, esModuleInterop: true, resolveJsonModule: true, isolatedModules: truemodule: NodeNextmoduleResolution: NodeNext这是 Node.js 原生 ESM 支持下的推荐组合。NodeNext 解析严格遵循package.json的type字段type: module时.ts按 ESM、.js按 CJS 处理能准确模拟 Node 的真实运行时行为types: [node]注入process、Buffer、__dirnameESM 下需另行处理等 Node 全局类型sourceMap: true产出 source map便于线上错误堆栈还原其余选项与 base 保持一致保证 Node 项目同样处于严格检查之下。七、vite.json面向 Vite 配置文件的轻量方案vite.json 是体系中最轻的一份专门服务vite.config.ts这类构建配置文件composite: true, module: ESNext, moduleResolution: bundler, allowSyntheticDefaultImports: true, types: [node], include: [vite.config.ts]它继承node.json将模块解析切换为bundler策略、开启composite以便被主 tsconfig 以references引用并且include直接锁定为vite.config.ts单个文件。仓库中多个示例项目如 examples/demos/react-demo/tsconfig.node.json、examples/guides/react-apollo/tsconfig.node.json正是用这种前端主配置 vite.node 配置的组合来覆盖同一目录下的两类代码。八、如何使用继承、覆写与创建新项目8.1 标准继承写法在子项目tsconfig.json中通过extends字段继承对应基础配置相对路径从子项目自身出发计算{ $schema: https://json.schemastore.org/tsconfig, extends: ../../configs/tsconfig/frontend.json, compilerOptions: { // 项目专属覆写放在这里 } }8.2 仓库内的真实继承示例Nhost 仓库中实际生效的继承写法相对路径均从各子项目自身出发// packages/nhost-js/tsconfig.json库/SDK { extends: ../../build/configs/tsconfig/library.json, compilerOptions: { lib: [ESNext, DOM], jsx: react-jsx, outDir: ./dist, paths: { nhost/nhost-js: [src/index.ts] } } } // examples/guides/react-query/tsconfig.json前端应用 { $schema: https://json.schemastore.org/tsconfig, extends: ../../../build/configs/tsconfig/frontend.json, include: [./src/**/*.ts, ./src/**/*.tsx], references: [{ path: ./tsconfig.node.json }] }8.3 创建新项目的推荐流程结合 build/configs/tsconfig/README.md 中 Creating New Projects 一节的说明判定项目类型根据项目是库/SDK、前端应用、Node 应用还是构建配置选择library.json、frontend.json、node.json或vite.json作为继承源创建最小 tsconfig新建tsconfig.json用extends指向 build/configs/tsconfig 目录下对应的基础配置只添加项目专属差异如include/exclude范围、路径别名、特定lib、产物目录等避免重复声明 base 中已有的严格检查项。8.4 覆写注意事项extends是浅层合并子项目compilerOptions中的同名键会整体覆盖父配置因此覆写时需显式补齐被覆盖键的完整值例如覆写lib时必须重新列出全部需要的库数组类型的选项如include、exclude、lib、types同样遵循覆盖语义不会被自动合并若某份基础配置的严格选项对当前项目过严例如历史存量代码无法通过verbatimModuleSyntax应像 packages/stripe-graphql-js/tsconfig.json 那样在子项目里显式关闭并留下可追踪的记录而不是放任不管。九、新增集中式配置的规范build/configs/README.md 的 Adding New Configurations 一节为仓库贡献者定义了新增集中配置的流程新建一个命名恰当的子目录例如为新的工具链建立独立目录在子目录内包含一份 README.md说明该配置的用途与用法同时记录配置的使用方式与取舍理由——怎么用与为什么这么配缺一不可这保证了后续维护者能理解每项选项背后的意图而不是盲目照抄。这套配置 文档 理由三位一体的约定正是该目录能够长期作为仓库 TypeScript 标准单一可信源的根本保障。十、总结一套配置管住整个 monorepo纵观 Nhost 仓库这套 build/configs/tsconfig 配置体系的价值可以归结为三点分层继承、职责单一base.json守住全部项目的类型安全底线strictnoUncheckedIndexedAccess等十余项严格检查library/frontend/node/vite各自面向一类场景补充环境与产出配置互不干扰严格模式贯穿始终从仓库的 npm 包packages/nhost-js/tsconfig.json、packages/stripe-graphql-js/tsconfig.json到示例工程examples/guides/react-query/tsconfig.json 等所有 TypeScript 代码都处于统一的高强度类型检查之下变更一处、全局生效当需要升级编译目标或收紧检查规则时只需修改 base.json 等基础文件所有继承它的子项目在下次构建时自动同步新标准。对于正在搭建或重构 monorepo 的团队这套方案提供了一个可复用的参考样板先沉淀一份覆盖严格类型检查的base.json再按库 / 前端 / Node / 构建工具拆分场景配置最后用extends让每个子项目只保留属于自己的差异——配置的复杂度被收敛在一处标准的执行力却贯穿整个仓库。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nhost 仓库统一 TypeScript 配置体系：基于 build/configs/tsconfig 的集中式 tsconfig 实践指南
Nhost 仓库统一 TypeScript 配置体系基于 build/configs/tsconfig 的集中式 tsconfig 实践指南【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost 是一个开源的 Firebase 替代方案The Open Source Firebase Alternative with GraphQL其仓库是一个包含 Go 服务端、前端 Dashboard、文档站、落地页与多个 npm 包的多语言 monorepo。为了让散落在各处的 TypeScript 项目保持一致的编译与类型检查标准仓库在 build/configs/tsconfig 目录下维护了一套可被任意子项目通过extends继承的集中式 TypeScript 基础配置。本文将以该目录下的 README.md 与 build/configs/README.md 为骨架结合仓库内真实 JSON 配置与下游项目的实际继承方式完整讲解这套配置的文件组成、每一项编译选项的含义、各类项目如何选用与覆写以及如何在此基础上创建新项目。一、为什么需要集中式 tsconfig配置即标准在大型 monorepo 中TypeScript 配置最容易出现的问题是每个子项目一套配置、标准各说各话有人开了strict有人没开有人用 CommonJS有人用 ESM包名路径 alias 各写各的。最终结果是类型检查形同虚设跨项目协作成本急剧上升。build/configs/README.md 明确说明了这套集中式配置目录的三个核心收益一致性Consistency所有项目遵循同一套编译标准与最佳实践避免同一仓库内出现互相冲突的 tsconfig可维护性Maintainability配置变更只需在一处完成即可通过继承传播到所有下游项目无需逐个项目手工同步快速上手Onboarding新项目可以直接继承现成配置快速启动不必从零推敲每一项编译选项。这正是 monorepo 场景下配置即代码、配置即标准的典型实践标准定义在单一可信源single source of truth中子项目只保留真正属于自己的差异项。二、配置文件全景base / library / frontend / node / vitebuild/configs/tsconfig/README.md 列出的五份基础配置各自面向一类项目其依赖关系如下配置文件面向场景继承链base.json所有项目共用的核心设置无最底层library.json库与 SDK 包需要产出声明文件base.jsonfrontend.json前端应用React、Next.jsbase.jsonnode.jsonNode.js 应用与脚本base.jsonvite.jsonVite 配置文件vite.config.tsnode.json整个体系的顶层入口是 build/configs/README.md它负责说明有哪些配置、如何使用、如何新增而 build/configs/tsconfig/README.md 则深入每一份 JSON 的具体语义。下面逐份拆解。三、base.json所有项目的共同基线base.json 是整棵继承树的根定义了仓库内所有 TypeScript 项目都必须遵守的编译与类型检查基线。其核心配置可分为四组3.1 环境与特性Environment and Featureslib: [ESNext], target: ES2022, module: ESNext, moduleDetection: force, skipLibCheck: truetarget: ES2022输出目标为 ES2022可在现代 Node.js 与浏览器上直接利用原生 class 字段、Array.at、Object.hasOwn等新特性module: ESNextlib: [ESNext]使用最新的 ESM 模块语义与最新标准库类型配合现代打包器使用moduleDetection: force强制所有文件都按 ES 模块处理避免出现脚本文件与模块文件混用导致的隐式全局变量问题skipLibCheck: true跳过.d.ts声明文件的类型检查显著加快编译速度代价是声明文件中的错误不被检查这是多数大型项目的通行取舍。3.2 类型检查Type Checking——严格模式全家桶strict: true, noFallthroughCasesInSwitch: true, noImplicitOverride: true, noImplicitReturns: true, noUnusedLocals: true, noUnusedParameters: true, noUncheckedIndexedAccess: true, noPropertyAccessFromIndexSignature: true, allowUnusedLabels: false, allowUnreachableCode: false这一组是整个配置中含金量最高的部分远超出普通strict: true的基础要求strict: true一次性开启strictNullChecks、noImplicitAny、strictFunctionTypes、strictPropertyInitialization等全部严格检查noUncheckedIndexedAccess访问数组或索引签名时结果类型自动带上undefined强制开发者处理越界/缺键情况——这是 Nhost 前端代码大量使用可空判定的来源之一noPropertyAccessFromIndexSignature禁止用.语法访问索引签名属性必须写成obj[key]让来自索引签名的访问在代码层面显式化noImplicitOverride覆写基类方法时必须显式写override关键字防止因拼写错误静默产生新方法noImplicitReturns所有代码路径都必须显式返回杜绝漏 return 但类型上恰好兼容的隐性 bugnoUnusedLocals/noUnusedParameters未使用的局部变量与参数直接报错保证提交的代码干净无死代码allowUnreachableCode: false与allowUnusedLabels: false不可达代码与未使用标签一律视为错误。3.3 模块解析Module ResolutionesModuleInterop: true, resolveJsonModule: true, forceConsistentCasingInFileNames: trueesModuleInterop: true允许import React from react这类默认导入写法是处理 CJS 包与 ESM 语法互操作的关键开关resolveJsonModule: true可直接import data from ./data.jsonforceConsistentCasingInFileNames: true强制文件引用大小写一致避免在大小写不敏感文件系统上开发、部署到 Linux大小写敏感后报错的经典坑。3.4 高级选项Advanced OptionsverbatimModuleSyntax: true, isolatedModules: trueverbatimModuleSyntax: true类型导入必须写成import type { Foo }运行时导入与类型导入在语法层面被强制区分配合打包器可安全剔除类型代码isolatedModules: true保证每个文件可被独立转译符合 esbuild、Babel 等单文件转译器的要求防止跨文件类型依赖导致单文件转译出错。3.5 默认排除项exclude: [node_modules, **/dist, **/build]base.json统一排除了node_modules与产物目录子项目在继承时可根据自身需求追加排除规则。四、library.json面向库与 SDK 的产出配置library.json 面向需要对外发布、必须生成类型声明文件的库与 SDK 包Nhost 的 npm 包即是典型。它继承base.json后追加了产出相关配置declaration: true, declarationMap: true, sourceMap: true, outDir: ./dist, noEmit: false, composite: true, importHelpers: true, moduleResolution: node, types: [node], include: [src/**/*]declaration: truedeclarationMap: true生成.d.ts声明文件与声明源映射让使用方的编辑器可以跳转到 .ts 源码这是 SDK 体验的关键sourceMap: true同时输出.js.map便于调试发布后的代码outDir: ./dist统一产物目录noEmit: false明确允许输出base.json本身不设置noEmit此处显式声明语义composite: true开启工程引用Project References支持配合declaration使该包可被其他项目增量引用importHelpers: true将__awaiter等辅助函数收敛到tslib避免每个文件重复内联缩小包体积moduleResolution: node库包采用 Node 风格解析保证发布后在各类消费方环境中都能被正确解析types: [node]仅注入 Node 类型include: [src/**/*]exclude中的**/*.test.ts、**/*.spec.ts、**/__tests__/**编译范围限定在src且自动把测试文件排除在产物之外。仓库内的真实继承案例packages/nhost-js/tsconfig.json 继承library.json并追加了lib: [ESNext, DOM]、jsx: react-jsx与一组路径别名如nhost/nhost-js/auth→src/auth/index.ts、nhost/nhost-js/storage→src/storage/index.ts这些别名让 SDK 内部模块既能独立导入又保持对外一致packages/stripe-graphql-js/tsconfig.json 继承library.json仅以verbatimModuleSyntax: false和outDir: ./dist两处做最小化覆写——直观展示了继承 少量自定义的推荐姿势。五、frontend.json面向 React / Next.js 前端的配置frontend.json 面向浏览器前端React、Next.js 等同样继承base.jsonlib: [ESNext, DOM, DOM.Iterable], jsx: react-jsx, moduleResolution: bundler, allowImportingTsExtensions: true, noEmit: true, allowJs: true, allowSyntheticDefaultImports: true, incremental: true, plugins: [], include: [src/**/*, **/*.ts, **/*.tsx]lib: [ESNext, DOM, DOM.Iterable]在 base 的 ESNext 之上补入 DOM 与 DOM.Iterable 类型使document、NodeList迭代等浏览器 API 可用jsx: react-jsx使用 React 17 的自动 JSX 运行时无需在每个文件显式import ReactmoduleResolution: bundler面向 Vite、Webpack、Next.js 等打包器的新式解析策略允许无扩展名导入天然适配package.json的exports字段allowImportingTsExtensions: true允许import ./foo.ts这类带扩展名导入需要与noEmit搭配因为产物由打包器产出而非 tscnoEmit: true前端项目的类型检查交给打包器与 CItsc 只做校验不产出文件allowJs: true允许混入 JS 文件便于存量 JS 代码渐进迁移allowSyntheticDefaultImports: true配合esModuleInterop放宽 CJS 模块的默认导入incremental: true开启增量编译配合.tsbuildinfo缓存加速后续构建plugins: []预留空插件位注释说明Next.js 项目可在此注入 Next 插件非 Next.js 项目会自动忽略该项。仓库内的真实继承案例examples/guides/react-query/tsconfig.json 继承frontend.jsoninclude限定./src/**/*.ts(x)并通过references: [{ path: ./tsconfig.node.json }]关联配套的 Node 侧配置tsconfig.node.json则继承vite.json——这是 Vite 脚手架标准的双 tsconfig结构dashboard/tsconfig.json 未直接继承该文件而是自行声明了一套与frontend.json高度同构的选项strict、moduleResolution: bundler、jsx: react-jsx、noEmit、incremental等并追加了/*等路径别名与noImplicitAny: false、useUnknownInCatchVariables: false等定制项可作为集中配置演进过程中存量项目渐进对齐的参照。六、node.json面向 Node.js 应用与脚本node.json 面向 Node.js 服务端代码与工具脚本module: NodeNext, moduleResolution: NodeNext, target: ES2022, lib: [ESNext], sourceMap: true, types: [node], allowJs: true, esModuleInterop: true, resolveJsonModule: true, isolatedModules: truemodule: NodeNextmoduleResolution: NodeNext这是 Node.js 原生 ESM 支持下的推荐组合。NodeNext 解析严格遵循package.json的type字段type: module时.ts按 ESM、.js按 CJS 处理能准确模拟 Node 的真实运行时行为types: [node]注入process、Buffer、__dirnameESM 下需另行处理等 Node 全局类型sourceMap: true产出 source map便于线上错误堆栈还原其余选项与 base 保持一致保证 Node 项目同样处于严格检查之下。七、vite.json面向 Vite 配置文件的轻量方案vite.json 是体系中最轻的一份专门服务vite.config.ts这类构建配置文件composite: true, module: ESNext, moduleResolution: bundler, allowSyntheticDefaultImports: true, types: [node], include: [vite.config.ts]它继承node.json将模块解析切换为bundler策略、开启composite以便被主 tsconfig 以references引用并且include直接锁定为vite.config.ts单个文件。仓库中多个示例项目如 examples/demos/react-demo/tsconfig.node.json、examples/guides/react-apollo/tsconfig.node.json正是用这种前端主配置 vite.node 配置的组合来覆盖同一目录下的两类代码。八、如何使用继承、覆写与创建新项目8.1 标准继承写法在子项目tsconfig.json中通过extends字段继承对应基础配置相对路径从子项目自身出发计算{ $schema: https://json.schemastore.org/tsconfig, extends: ../../configs/tsconfig/frontend.json, compilerOptions: { // 项目专属覆写放在这里 } }8.2 仓库内的真实继承示例Nhost 仓库中实际生效的继承写法相对路径均从各子项目自身出发// packages/nhost-js/tsconfig.json库/SDK { extends: ../../build/configs/tsconfig/library.json, compilerOptions: { lib: [ESNext, DOM], jsx: react-jsx, outDir: ./dist, paths: { nhost/nhost-js: [src/index.ts] } } } // examples/guides/react-query/tsconfig.json前端应用 { $schema: https://json.schemastore.org/tsconfig, extends: ../../../build/configs/tsconfig/frontend.json, include: [./src/**/*.ts, ./src/**/*.tsx], references: [{ path: ./tsconfig.node.json }] }8.3 创建新项目的推荐流程结合 build/configs/tsconfig/README.md 中 Creating New Projects 一节的说明判定项目类型根据项目是库/SDK、前端应用、Node 应用还是构建配置选择library.json、frontend.json、node.json或vite.json作为继承源创建最小 tsconfig新建tsconfig.json用extends指向 build/configs/tsconfig 目录下对应的基础配置只添加项目专属差异如include/exclude范围、路径别名、特定lib、产物目录等避免重复声明 base 中已有的严格检查项。8.4 覆写注意事项extends是浅层合并子项目compilerOptions中的同名键会整体覆盖父配置因此覆写时需显式补齐被覆盖键的完整值例如覆写lib时必须重新列出全部需要的库数组类型的选项如include、exclude、lib、types同样遵循覆盖语义不会被自动合并若某份基础配置的严格选项对当前项目过严例如历史存量代码无法通过verbatimModuleSyntax应像 packages/stripe-graphql-js/tsconfig.json 那样在子项目里显式关闭并留下可追踪的记录而不是放任不管。九、新增集中式配置的规范build/configs/README.md 的 Adding New Configurations 一节为仓库贡献者定义了新增集中配置的流程新建一个命名恰当的子目录例如为新的工具链建立独立目录在子目录内包含一份 README.md说明该配置的用途与用法同时记录配置的使用方式与取舍理由——怎么用与为什么这么配缺一不可这保证了后续维护者能理解每项选项背后的意图而不是盲目照抄。这套配置 文档 理由三位一体的约定正是该目录能够长期作为仓库 TypeScript 标准单一可信源的根本保障。十、总结一套配置管住整个 monorepo纵观 Nhost 仓库这套 build/configs/tsconfig 配置体系的价值可以归结为三点分层继承、职责单一base.json守住全部项目的类型安全底线strictnoUncheckedIndexedAccess等十余项严格检查library/frontend/node/vite各自面向一类场景补充环境与产出配置互不干扰严格模式贯穿始终从仓库的 npm 包packages/nhost-js/tsconfig.json、packages/stripe-graphql-js/tsconfig.json到示例工程examples/guides/react-query/tsconfig.json 等所有 TypeScript 代码都处于统一的高强度类型检查之下变更一处、全局生效当需要升级编译目标或收紧检查规则时只需修改 base.json 等基础文件所有继承它的子项目在下次构建时自动同步新标准。对于正在搭建或重构 monorepo 的团队这套方案提供了一个可复用的参考样板先沉淀一份覆盖严格类型检查的base.json再按库 / 前端 / Node / 构建工具拆分场景配置最后用extends让每个子项目只保留属于自己的差异——配置的复杂度被收敛在一处标准的执行力却贯穿整个仓库。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考