@flywen/tsconfig 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# @flywen/ts-config
+
+Shared TypeScript configurations for multiple environments.
+
+## Installation
+
+```bash
+npm install -D @flywen/ts-config
+# or
+yarn add -D @flywen/ts-config
+# or
+pnpm add -D @flywen/ts-config
+```
+
+## Usage
+
+Extend the configuration in your `tsconfig.json`:
+
+### Base Configuration (tsconfig.base.json)
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.base.json"
+}
+```
+
+### Node.js Application (tsconfig.node.json)
+
+For Node.js applications (not libraries):
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.node.json"
+}
+```
+
+### Node.js Library (tsconfig.node-lib.json)
+
+For Node.js libraries that need declaration files:
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.node-lib.json"
+}
+```
+
+### React (tsconfig.react.json)
+
+For React applications with Vite/modern bundlers:
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.react.json"
+}
+```
+
+### Vue (tsconfig.vue.json)
+
+For Vue 3 applications with Vite:
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.vue.json"
+}
+```
+
+### Web Library (tsconfig.web-lib.json)
+
+For web libraries that need declaration files:
+
+```json
+{
+  "extends": "@flywen/ts-config/tsconfig.web-lib.json"
+}
+```
+
+## Configurations
+
+### tsconfig.base.json
+
+Base configuration with shared settings:
+- All strict mode options enabled
+- `esModuleInterop: true`
+- `skipLibCheck: true`
+- `forceConsistentCasingInFileNames: true`
+- `resolveJsonModule: true`
+- `declaration: true`
+- `declarationMap: true`
+- `sourceMap: true`
+
+### tsconfig.node.json
+
+Node.js 18+ application configuration:
+- `target: "ES2022"`
+- `module: "NodeNext"`
+- `moduleResolution: "NodeNext"`
+- `lib: ["ES2022"]`
+- `outDir: "./dist"`
+- `rootDir: "./src"`
+- `types: ["node"]`
+
+### tsconfig.node-lib.json
+
+Node.js library configuration:
+- Inherits from base
+- `target: "ES2022"`
+- `module: "NodeNext"`
+- `moduleResolution: "NodeNext"`
+- `declaration: true`
+- `declarationMap: true`
+- `types: ["node"]`
+
+### tsconfig.react.json
+
+React (Vite/modern bundler) configuration:
+- `target: "ESNext"`
+- `module: "ESNext"`
+- `moduleResolution: "bundler"`
+- `jsx: "react-jsx"`
+- `jsxImportSource: "react"`
+- `lib: ["DOM", "DOM.Iterable", "ESNext"]`
+- `noEmit: true` (Vite handles compilation)
+- Path aliases configured (`@/*`)
+
+### tsconfig.vue.json
+
+Vue 3 (Vite) configuration:
+- `target: "ESNext"`
+- `module: "ESNext"`
+- `moduleResolution: "bundler"`
+- `jsx: "preserve"`
+- `jsxImportSource: "vue"`
+- `lib: ["ESNext", "DOM", "DOM.Iterable"]`
+- `types: ["vite/client"]`
+- `noEmit: true` (Vite handles compilation)
+- Path aliases configured (`@/*`)
+- Includes `.vue` files
+
+### tsconfig.web-lib.json
+
+Web library configuration:
+- `target: "ES2020"`
+- `module: "ESNext"`
+- `moduleResolution: "bundler"`
+- `lib: ["ESNext", "DOM", "DOM.Iterable"]`
+- `declaration: true`
+- `declarationMap: true`
+- `outDir: "./dist"`
+- `rootDir: "./src"`
+
+## Notes
+
+- All configurations extend from `tsconfig.base.json`
+- React and Vue configs assume usage with Vite or similar modern bundlers
+- Node.js configs support both ESM (`NodeNext`) and CJS
+- Path aliases (`@/*`) are pre-configured for React, Vue, and web-lib configs
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flywen/tsconfig",
+  "version": "1.0.0",
+  "description": "Shared TypeScript configurations for multiple environments (Node.js, React, Vue, Web Library)",
+  "type": "module",
+  "files": [
+    "tsconfig.base.json",
+    "tsconfig.node.json",
+    "tsconfig.node-lib.json",
+    "tsconfig.react.json",
+    "tsconfig.vue.json",
+    "tsconfig.web-lib.json"
+  ],
+  "keywords": [
+    "typescript",
+    "tsconfig",
+    "configuration",
+    "node",
+    "react",
+    "vue",
+    "library",
+    "web"
+  ],
+  "author": "flywen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goatail/tsconfig.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gotail/tsconfig/issues"
+  },
+  "homepage": "https://github.com/gotail/tsconfig#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tsconfig.base.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    /* ========== 严格检查（所有配置共享） ========== */
+    "strict": true,                        // 开启所有严格类型检查（类型安全的基石）
+    "noImplicitAny": true,                 // 禁止隐式 any 类型，强制显式声明类型
+    "strictNullChecks": true,              // 严格 null/undefined 检查，避免空指针错误
+    "strictFunctionTypes": true,           // 严格函数类型检查，防止参数类型错误
+    "strictBindCallApply": true,           // 严格 bind/call/apply 检查
+    "strictPropertyInitialization": true,  // 严格属性初始化检查（类属性必须初始化）
+    "noImplicitThis": true,                // 禁止隐式 this，必须显式声明 this 类型
+    "alwaysStrict": true,                  // 始终以严格模式解析（生成 "use strict"）
+
+    /* ========== 模块解析通用配置 ========== */
+    "esModuleInterop": true,               // 允许 CommonJS 和 ES Module 互操作（如 import * as fs from 'fs'）
+    "forceConsistentCasingInFileNames": true, // 强制文件名大小写一致（避免 macOS/Windows 不兼容）
+    "resolveJsonModule": true,             // 允许导入 .json 文件（如 import config from './config.json'）
+    "skipLibCheck": true,                  // 跳过 node_modules 类型检查（加快编译速度）
+
+    /* ========== 通用输出配置 ========== */
+    "declaration": true,                   // 生成 .d.ts 类型声明文件（库项目必须）
+    "declarationMap": true,               // 生成 .d.ts.map 源码映射（允许用户跳转到源码）
+    "sourceMap": true,                    // 生成 .js.map 源码映射（便于调试）
+
+    /* ========== 其他通用配置 ========== */
+    "removeComments": false                // 保留注释（库项目重要，JSDoc 注释会包含在 .d.ts 中）
+  },
+  "exclude": ["node_modules", "dist", "build"]
+}

package/tsconfig.node-lib.json

@@ -0,0 +1,24 @@
+{
+  "extends": "./tsconfig.base.json",
+
+  "compilerOptions": {
+    /* ========== Node.js 库配置（继承 base.json） ========== */
+    "target": "ES2022",                   // Node.js 18+ 推荐使用 ES2022（支持 Top-level await）
+    "module": "NodeNext",                 // Node.js 原生 ESM/CJS 双模式支持
+    "moduleResolution": "NodeNext",       // 配合 NodeNext，遵循 Node.js 文件寻址规则
+    "lib": ["ES2022"],                   // 仅包含 ES 语法，不含 DOM
+
+    /* ========== 库的产物配置 ========== */
+    "declaration": true,                  // 必须！生成 .d.ts 文件，库的使用者才能看到类型提示
+    "declarationMap": true,               // 生成 .d.ts.map，允许使用者调试时跳转到你的 TS 源码
+    "sourceMap": true,                    // 生成 .js.map，方便在 Node 中进行错误堆栈追踪
+    "outDir": "./dist",                   // 编译后的文件存放路径
+    "rootDir": "./src",                   // 源码根目录
+
+    /* ========== Node.js 类型注入 ========== */
+    "types": ["node"]                     // 显式引入 @types/node，确保可以使用 process, fs, path 等
+  },
+
+  "include": ["src/**/*.ts"],             // 仅包含源码
+  "exclude": ["node_modules", "dist", "test", "**/*.spec.ts", "**/*.test.ts"] // 排除测试文件和产物
+}

package/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.base.json",
+
+  "compilerOptions": {
+    /* ========== Node.js 应用配置（继承 base.json） ========== */
+    "target": "ES2022",                   // Node.js 18+ 推荐使用 ES2022（支持 Top-level await）
+    "module": "NodeNext",                 // Node.js 原生 ESM/CJS 双模式支持
+    "moduleResolution": "NodeNext",       // 配合 NodeNext，遵循 Node.js 文件寻址规则
+    "lib": ["ES2022"],                   // 仅包含 ES 语法，不含 DOM（Node 无浏览器 API）
+
+    /* ========== 应用输出配置 ========== */
+    "outDir": "./dist",                   // 编译产物输出目录
+    "rootDir": "./src",                   // 源码根目录
+    "removeComments": false,              // 保留注释（便于调试和阅读）
+
+    /* ========== Node.js 特定类型 ========== */
+    "types": ["node"],                    // 注入 Node.js 类型（process, fs, path 等）
+    "sourceMap": true                     // 生成 source map（便于 Node 错误堆栈追踪）
+  },
+
+  "include": ["src/**/*"],               // 包含 src 下所有文件
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"] // 排除测试文件和产物
+}

package/tsconfig.react.json

@@ -0,0 +1,38 @@
+{
+  "extends": "./tsconfig.base.json",
+
+  "compilerOptions": {
+    /* ========== React 与 JSX 支持 ========== */
+    "jsx": "react-jsx",                   // 关键：针对 React 17+ 的自动 JSX 转换，无需在每个文件 import React
+    "jsxImportSource": "react",           // 指定 JSX 编译的运行时库
+
+    /* ========== 环境与目标 ========== */
+    "target": "ESNext",                   // 编译到最新的 JS 版本，适合现代浏览器
+    "lib": ["DOM", "DOM.Iterable", "ESNext"], // 包含浏览器 DOM 接口和最新 ES 语法
+    "module": "ESNext",                   // 使用 ESM 模块系统
+    "moduleResolution": "bundler",        // TS 5.0+ 推荐，适配 Vite/Webpack 等打包工具的解析规则
+    "useDefineForClassFields": true,      // 强制类字段定义符合标准 ES 规范
+
+    /* ========== 严格性与质量 ========== */
+    // 注意：strict 等已由 base.json 继承，此处不再重复
+
+    /* ========== 模块兼容性 ========== */
+    "allowJs": true,                      // 允许项目中存在 .js 或 .jsx 文件（适合迁移旧项目）
+    "allowSyntheticDefaultImports": true, // 允许没有默认导出的模块也可以用 default 导入
+    "isolatedModules": true,              // 必须！确保每个文件可独立编译，适配 Vite 使用的 esbuild
+
+    /* ========== 构建输出设置 ========== */
+    "noEmit": true,                       // TS 只做检查，不输出 JS 文件。JS 转换由 Vite/Babel 完成
+    "incremental": true,                  // 开启增量编译，提升二次检查速度
+    // sourceMap 由 base.json 继承
+
+    /* ========== 路径别名 ========== */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]                    // 配置 @ 指向 src 目录
+    }
+  },
+
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts"], // 包含的文件
+  "exclude": ["node_modules", "dist", "build"]                 // 排除的文件
+}

package/tsconfig.vue.json

@@ -0,0 +1,51 @@
+{
+  "extends": "./tsconfig.base.json",
+
+  "compilerOptions": {
+    /* ========== Vue 浏览器环境配置 ========== */
+    "target": "ESNext",                          // 编译到最新的 JS 版本，适合现代浏览器
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],   // 包含浏览器 DOM 接口和最新 ES 语法
+    "module": "ESNext",                          // 使用 ESM 模块系统
+    "moduleResolution": "bundler",               // TS 5.0+ 推荐，适配 Vite 等打包工具的解析规则
+    "useDefineForClassFields": true,             // 强制类字段定义符合标准 ES 规范（Vue 3 推荐）
+
+    /* ========== JSX/TSX 处理 ========== */
+    "jsx": "preserve",                           // 保留 JSX 原样，由 Vite 插件完成转换
+    "jsxImportSource": "vue",                    // 指定 JSX 的工厂函数来源
+
+    /* ========== 模块兼容性 ========== */
+    "allowJs": true,                             // 允许项目中存在 .js 文件
+    "allowSyntheticDefaultImports": true,        // 允许没有默认导出的模块也可以用 default 导入
+    "isolatedModules": true,                     // 必须！确保每个文件可独立编译，适配 Vite 使用的 esbuild
+
+    /* ========== 构建输出设置 ========== */
+    "noEmit": true,                              // TS 只做检查，不输出 JS 文件（Vite 负责编译）
+    "incremental": true,                         // 开启增量编译，提升二次检查速度
+
+    /* ========== Vue 类型注入 ========== */
+    "types": ["vite/client"],                    // 注入 Vite 特有的全局类型（如 import.meta.env）
+
+    /* ========== 路径别名 ========== */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]                        // 配置 @ 指向 src 目录
+    },
+
+    /* ========== 代码质量检查 ========== */
+    "noUnusedLocals": true,                      // 定义的变量若未使用则报错（保持代码整洁）
+    "noUnusedParameters": true,                  // 函数参数若未使用则报错
+    "noFallthroughCasesInSwitch": true           // 防止 switch 语句忘记写 break 导致穿透
+  },
+
+  /* ========== 包含与排除 ========== */
+  "include": [
+    "src/**/*.ts",                               // 检查 src 下所有的 .ts 文件
+    "src/**/*.d.ts",                             // 检查 src 下所有的类型声明文件
+    "src/**/*.tsx",                              // 检查 src 下所有的 .tsx 文件
+    "src/**/*.vue"                               // 关键！检查 src 下所有的 .vue 文件（Vue 插件会处理）
+  ],
+  "exclude": [
+    "node_modules",                              // 排除依赖库
+    "dist"                                       // 排除打包产物
+  ]
+}

package/tsconfig.web-lib.json

@@ -0,0 +1,41 @@
+{
+  "extends": "./tsconfig.base.json",
+
+  "compilerOptions": {
+    /* ========== 环境与目标 - 针对浏览器 ========== */
+    "target": "ES2020",                          // 通常编译到较新的版本，由使用者的打包工具决定是否进一步降级
+    "useDefineForClassFields": true,             // 使用标准的 ECMAScript 类字段定义方式（Vue 3/现代 JS 推荐）
+    "module": "ESNext",                          // 必须使用 ESM 模块，方便使用者进行 Tree-shaking（摇树优化）
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],   // 核心：告诉 TS 运行在浏览器环境，可以使用 window, document 等
+    "moduleResolution": "bundler",               // 现代库开发的标准，模拟 Vite/Webpack 等打包工具的寻址逻辑
+
+    /* ========== 库专用的产物配置 ========== */
+    "declaration": true,                         // 必须！生成 .d.ts 类型声明文件，别人引用你时才有代码提示
+    "declarationMap": true,                      // 可选：生成类型映射文件，允许使用者"跳转到定义"时直接定位到你的 TS 源码
+    "emitDeclarationOnly": false,               // 如果只让 tsc 生成类型（JS 交给 Vite 处理），则设为 true
+    "sourceMap": true,                           // 生成 .map 文件，方便在浏览器控制台调试源码
+    "outDir": "./dist",                          // 编译产物的存放路径
+
+    /* ========== 严格检查 - 保证库的质量 ========== */
+    // 注意：strict 等已由 base.json 继承，此处不再重复
+    // "skipLibCheck": true 已由 base.json 继承
+
+    /* ========== 模块与兼容性 ========== */
+    "esModuleInterop": true,                     // 允许像 import React from 'react' 这样导入 CommonJS 模块
+    "isolatedModules": true,                     // 确保每个文件都能独立编译（Vite/esbuild 的硬性要求）
+
+    /* ========== 路径别名 ========== */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]                          // 设置库内部的路径快捷方式
+    }
+  },
+
+  "include": ["src/**/*.ts"],                   // 只编译 src 目录下的源码
+  "exclude": [                                  // 排除不需要打包的文件
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}