@ aleph- alpha/ tsconfig- 前端

共享, 严格默认 Aleph Alpha 前端工程的TypeScript配置.

它载着一小批 可堆叠预设. 想法:所有真正 可分享 (语言目标,模块分辨率,严格的家庭,通用质量旗帜) 住在一个被审查过的地方,一切 具体项目 (单位:千美元)paths, (中文(简体) ), include编号 :exclude, (中文(简体) ), 发射布局、环境 types留在消费项目中。 每个 compilerOption (单位:千美元) 预设套装可以被本地覆盖——预设是基线而不是紧身衣.

pnpm add -D @aleph-alpha/tsconfig-frontend

为何四个预设而不是一个?

base 实值 单一可扩展的核心。 其他三个之所以存在是因为 TypeScript 编译 不同,相互排斥 语境 一个配置不能同时服务——以及 每个前端工程已经分开(a) tsconfig.app.json 浏览器代码 + a tsconfig.node.json 工具是事实上的标准:

• 浏览器/ Vue 代码需求 DOM libs + JSX; 节点工具必须 没有 有他们.
• 节点工具需求 types: ["node"]; 浏览器代码必须 没有 污染其全球范围.
• 发射的软件包 .d.ts 需求 declaration编号 :composite不发射的应用软件会出错.

折叠到一个配置中不会移除这个配置——它只会复制到 每个项目(并像太低那样引起错误) lib) (中文(简体) ). 预设器将其移入一地.

一览预设

赤裸裸的 @aleph-alpha/tsconfig-frontend 条目仍然解决(它映射到遗产平面 配置)用于后向相容性. 新代码应扩展上面四个预设之一.

/base

什麽 ——框架不可知的严格基准. 没有DOM,没有节点,没有JSX的假设.

设定 (所有其它预设的可共享核心基于概念):

{
  "target": "es2022",
  "module": "esnext",
  "moduleResolution": "bundler",
  "lib": ["es2022"],

  // strict family
  "strict": true,                     // implies noImplicitAny, strictNullChecks, ...
  "noUncheckedIndexedAccess": true,   // arr[i] / obj[key] is T | undefined
  "verbatimModuleSyntax": true,       // type-only imports must use `import type`
  "useDefineForClassFields": true,

  // safe bug-catchers (no emit impact, catch real bugs)
  "noImplicitOverride": true,         // overrides must be marked `override`
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true,

  // ergonomics
  "isolatedModules": true,
  "esModuleInterop": true,
  "forceConsistentCasingInFileNames": true,
  "importHelpers": true,
  "resolveJsonModule": true,
  "skipLibCheck": true,
  "sourceMap": true
}

为什么 ——这是整个矿石的严格性合同. noUncheckedIndexedAccess 编辑 捕虫者发现真正的缺陷; verbatimModuleSyntax 为捆绑者保持进口的明确性.

何时使用 ——纯类型脚本,没有浏览器或节点假设(例如a) utils 软件包).

如何使用

{
  "extends": "@aleph-alpha/tsconfig-frontend/base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts"]
}

/vue-app

什麽 ——为Vue Single-File组件和浏览器代码配置. 镜像 Vue 团队的官方 @vue/tsconfig/tsconfig.dom.json缩写(见 为什么预设是自成一体的) (中文(简体) ).

设定 (内线上) @vue/tsconfig 基线,已经提供 strict, (中文(简体) ), verbatimModuleSyntax, (中文(简体) ), useDefineForClassFields, (中文(简体) ), jsx: "preserve", (中文(简体) ), jsxImportSource: "vue", (中文(简体) ), noEmit:

{
  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  "types": ["vite/client"],
  "noImplicitOverride": true,
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true
}

为什么 —— 说 .vue 文件需要 JSX + DOM libs + Vue 的 jsxImportSource。镜像 @vue/tsconfig (而不是重新开发它) 给了我们Vue团队的战斗测试默认值; 重现上游 碰上时用手打印.

何时使用 - 包含下列内容的任何应用程序或组件库: .vue 文档。 实际联合来文/.d.ts 输出为 生产 视频 / vite-plugin-dts没有 tsc 这样啊 noEmit: true (从内线基线)是 这里正确.

如何使用

{
  "extends": "@aleph-alpha/tsconfig-frontend/vue-app",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

/lib

什麽 用于可建库软件包,通过该软件包发送声明类型 tsc。 。 。 .

设定 (续) ./base:

{
  "declaration": true,
  "composite": true,
  "lib": ["es2022", "dom", "dom.iterable"]
}

为什么 - 排放图书馆需要 declaration (至船舶) .d.ts和 composite (项目 参考文献/增量构建)。 这对应用来说是错误的,所以它们生活在自己的预设中.

何时 - 一个非Vue包,其 .d.ts 由 tsc (非由维特. 通常配对 a 当地 outDir编号 :rootDir。 。 。 .

怎么样

{
  "extends": "@aleph-alpha/tsconfig-frontend/lib",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts"]
}

说明: composite 实值 不兼容 outFile。如果包件捆绑其声明 输入单个文件通过 outFile,扩展 /base 改为添加 declaration + 键 emitDeclarationOnly 当地(见 outFile (原始内容存档于2018-09-21). gotcha between.

/node

什麽 ——为节点执行的工具文件配置,不是运出浏览器代码.

设定 (内线上) @tsconfig/node24 基线:

{
  "noEmit": true,
  "module": "esnext",
  "moduleResolution": "bundler",
  "types": ["node"],
  "noImplicitOverride": true,
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true
}

为什么 —— 说 vite.config.ts, (中文(简体) ), vitest.config.ts, (中文(简体) ), eslint.config.ts,构建脚本等 节点和需要节点全球/类型, 没有 dOM(英语:DOM). 把它们保存在一个单独的配置中意味着浏览器 代码从不意外地在节点类型和反之.

何时使用 - 那个 tsconfig.node.json 该类型检查您的配置/ 工具文件 .

如何使用

{
  "extends": "@aleph-alpha/tsconfig-frontend/node",
  "include": ["vite.config.ts", "vitest.config.ts", "eslint.config.ts"]
}

软件包拥有的对项目拥有的

在预设中( 可共享) : target, (中文(简体) ), module编号 :moduleResolution基线 lib严格 家庭,捕虫者, 和发射形状 /lib。仅通过更改软件包更改这些软件包 (所以每个消费者都一起行动).

在项目中( 总是本地的和压倒性的): paths + 键 baseUrl, (中文(简体) ), include编号 :exclude, (中文(简体) ), rootDir编号 :outDir编号 :tsBuildInfoFile环境 types, (中文(简体) ), references, (中文(简体) ), experimentalDecorators编号 :emitDecoratorMetadata,以及任何每个项目严格选择退出/选择进入.

为什么预设是自成一体的

这里没有扩展配置的预设 另一个软件包 —— 说 /vue-app 财务报告和审定财务报表 /node 内含 上游基线@vue/tsconfig, (中文(简体) ), @tsconfig/node24)而不是延长.

TypeScript 解析软件包样式 extends 节点解决导入的方式,走起 node_modules 并跟随符号链接。 其他读取工具 tsconfig.json 别 剧作家,用于 一个,只看里面 <the extending file>/node_modules/… - 所以用pnpm, 里面一个包自己的 依赖性在商店而不是软件包文件夹内存在,无法遵循 node.json → @tsconfig/node24 无法完全装入配置 :

Failed to load tsconfig file at …/apps/<app>-e2e/tsconfig.json:
Failed to resolve "extends" path "@tsconfig/node24/tsconfig.json"
referenced from …/node_modules/@aleph-alpha/tsconfig-frontend/node.json

保持每一个预先设定的自成一体可以消除整个失败的类别——对于Playwright和任何 其他工具 一个天真的解析器。 其代价是,必须用手重新出现上游起伏 原出地(包装+准确版本)记录在 "//" 键位于每个受影响的预设的顶端.

相对 extends 在内部 此软件包( e)/lib → ./base)是好的——每个工具都处理这个.

@vue/tsconfig 财务报告和审定财务报表 @tsconfig/node24 保留在本包中 dependencies 即使没有预设 继续扩展 这是故意的: 扔掉它们会打破任何消费者 extends 任意一个软件包 直接 并依靠它过境抵达。 它们被保存在后方 兼容性并预定在今后的主要项目中清除——如果直接延长其中之一,则宣布 在你身边 package.json。 。 。 .

常见的覆盖( G)

这些是真正的移民,都是合法的 当地 覆盖 :

• 需要一个新的JS内置 (单位:千美元)Array.prototype.toSorted =ES2023等吗?)? @vue/tsconfig 我们 预设目标为保守 lib。从本地跳出: "lib": ["ES2023", "DOM", "DOM.Iterable"]。这只影响类型检查 真实浏览器目标 .
• 代码使用 window/DOM 但扩展 /base? 吗? 添加 DOM 到 lib 当地: "lib": ["ES2022", "DOM"]。 。 。 . (或使用 /vue-app,包括DOM.)
• outFile 对于一个捆绑的 .d.ts? 吗? outFile 两者均不相容 composite 财务报告和审定财务报表 verbatimModuleSyntax扩展 /base设置 declaration + 键 emitDeclarationOnly + 键 outFile,以及 覆盖 "verbatimModuleSyntax": false 当地.
• 非配置文件的节点工具 (例如节点目标图书馆)? 扩展 /base 添加 "types": ["node"] 而不是说 /node (这迫使 noEmit) (中文(简体) ).
• 移动一个日期之前的代码库 noImplicitAny? 吗? 如果打开它 表面大量积压, 您可以临时设置 "noImplicitAny": false 本地并点出错误 打开 base 所以,新的/干净的代码保持严格的.

公约: 文档 原因 严格选择退出 公关说明,而不是作为一个 注释 tsconfig ——所以在后期取消重置后不会腐烂.