Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@quicksand-cloud/typescript-config) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@quicksand-cloud/typescript-config

QuickSand Cloud 的 TypeScript 配置包，提供多种场景下的 TypeScript 编译配置。

📦 安装

npm install --save-dev @quicksand-cloud/typescript-config

🚀 使用方法

基础配置

在项目根目录创建 tsconfig.json 文件：

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.base.json"
}

React 项目配置

对于 React 项目，使用 React 专用配置：

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.react.json",
  "compilerOptions": {
    "baseUrl": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Node.js 项目配置

对于 Node.js 项目，使用 Node.js 专用配置：

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.node.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

⚙️ 配置详情

基础配置 (tsconfig.base.json)

编译目标和模块

目标版本: ESNext
模块系统: preserve（保持原有模块语法）
模块解析: bundler（适配现代打包工具）
库文件: ESNext
JSX: react-jsx（React 17+ 新语法）

严格模式

严格模式: 全部启用
未使用变量检查: 启用
未使用参数检查: 禁用
Switch 语句检查: 启用
索引访问检查: 启用
隐式覆盖检查: 启用

代码生成

不生成文件: 启用（适合打包工具处理）
装饰器支持: 启用实验性装饰器
装饰器元数据: 启用
允许 JS 文件: 启用
ES 模块互操作: 启用

React 配置 (tsconfig.react.json)

继承基础配置，额外包含：

DOM 库: 支持浏览器 DOM API
DOM Iterable: 支持 DOM 迭代器
JSX: react-jsx 模式

Node.js 配置 (tsconfig.node.json)

继承基础配置，额外包含：

ts-node: 启用 ESM 支持
装饰器: 完整的装饰器支持

🎯 使用场景

1. 现代 Web 应用

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.react.json",
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"],
      "@/components/*": ["components/*"]
    }
  }
}

2. Node.js API 服务

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.node.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "types": ["node"]
  }
}

3. 全栈应用（多项目）

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.base.json",
  "references": [
    { "path": "./packages/frontend" },
    { "path": "./packages/backend" }
  ]
}

4. 库开发

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.base.json",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "noEmit": false
  }
}

🛠 与构建工具集成

Vite 集成

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  // Vite 会自动读取 tsconfig.json
  esbuild: {
    tsconfigRaw: {
      extends: '@quicksand-cloud/typescript-config/tsconfig.react.json',
    },
  },
});

Webpack 集成

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'ts-loader',
          options: {
            configFile: 'tsconfig.json',
          },
        },
      },
    ],
  },
};

Rollup 集成

// rollup.config.js
import typescript from '@rollup/plugin-typescript';

export default {
  plugins: [
    typescript({
      tsconfig: './tsconfig.json',
    }),
  ],
};

🔧 自定义配置

扩展基础配置

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    },
    "lib": ["ES2022", "DOM"],
    "target": "ES2022"
  },
  "include": ["src/**/*", "types/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

多项目配置

{
  "extends": "@quicksand-cloud/typescript-config/tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "incremental": true
  },
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/client" },
    { "path": "./packages/server" }
  ]
}

📋 依赖要求

typescript >= 5.0.0

⚠️ 注意事项

默认启用严格模式，可能需要修复现有代码的类型错误
noEmit 设置为 true，适合与打包工具配合使用
启用了实验性装饰器，如果不需要可以禁用
建议配合 @quicksand-cloud/oxlint-config 使用进行代码检查

🔄 与其他配置包的关系

本配置包是 QuickSand Cloud Specs 配置集合的一部分，建议与以下包配合使用：

@quicksand-cloud/oxlint-config - 代码检查
@quicksand-cloud/prettier-config - 代码格式化
@quicksand-cloud/lint-staged-config - Git 提交前检查
@quicksand-cloud/commitlint-config - 提交信息规范
@quicksand-cloud/specs - 配置管理工具

📄 许可证

MIT