mcpField
T
typescript-devdependencies

typescript-devdependencies

github.com/marius-townhouse开发644 次安装38 周前更新
代码仓库

关于 typescript-devdependencies

这项 TypeScript 项目配置技能说明为何 TypeScript 和 `@types` 包应放在 `devDependencies` 中，面向应用开发者和库作者讲解依赖分类。

主要功能

  1. 01区分开发依赖与运行时依赖
  2. 02说明 TypeScript 和 `@types` 的归类
  3. 03展示 package.json 配置示例
  4. 04涵盖依赖检查与发布

适用场景

  1. 01配置 TypeScript 项目
  2. 02在 package.json 中归类依赖
  3. 03准备发布 TypeScript 库

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/marius-townhouse/effective-typescript-skills --skill typescript-devdependencies

安装后在 Claude Code 中输入/typescript-devdependencies确认已加载。

详细介绍

将 TypeScript 和 @types 放入 devDependencies

概述

TypeScript 是开发工具，不会在运行时使用。同样，@types 包只包含类型声明，不包含运行时代码。两者都应安装为 devDependencies，而不是 dependencies。这样可以精简生产构建，并避免版本冲突。

无论是库作者还是应用开发者，理解 dependencies 和 devDependencies 之间的区别都至关重要。

何时使用此技能

  • 设置新的 TypeScript 项目
  • 安装 @types 包
  • 配置 package.json 依赖项
  • 发布 TypeScript 库
  • 管理项目依赖项

铁律

TypeScript 和 @types 包应放在 devDependencies 中。它们仅用于开发，不会在运行时使用。

检测

留意 package.json 中的这些问题：

{
  "dependencies": {
    "typescript": "^5.0.0",      // WRONG: Should be devDependency
    "@types/node": "^20.0.0",    // WRONG: Should be devDependency
    "@types/react": "^18.0.0"    // WRONG: Should be devDependency
  }
}

正确配置

{
  "devDependencies": {
    "typescript": "^5.2.2",
    "@types/node": "^20.0.0",
    "@types/react": "^18.2.0"
  },
  "dependencies": {
    "react": "^18.2.0"  // Runtime dependency
  }
}

安装命令

# TypeScript itself - dev dependency
npm install --save-dev typescript

# @types for runtime dependencies - also dev dependency
npm install react                    # Runtime dependency
npm install --save-dev @types/react  # Type definitions

# @types for Node.js built-ins
npm install --save-dev @types/node

为什么使用 devDependencies？

// TypeScript compiles away - not in output
const greeting: string = "Hello";  // Type annotation
// Compiles to:
const greeting = "Hello";  // No types in JS output

// @types packages contain only .d.ts files
// No runtime code - safe to exclude from production

发布库

{
  "name": "my-library",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "dependencies": {
    "lodash": "^4.17.0"  // Runtime dependency
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/lodash": "^4.14.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"  // User provides this
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  }
}

检查配置

# See what's in dependencies vs devDependencies
npm list --prod        # Production dependencies only
npm list --dev         # Dev dependencies only

# Check for misplaced TypeScript dependencies
npm ls typescript @types/*

抗压协议

设置依赖项时：

  1. 询问：它会在生产环境中运行吗？ TypeScript 和 @types 不会
  2. 为类型使用 --save-dev：始终对 @types 包使用
  3. 发布前检查：npm pack 会显示将要发布的内容
  4. 检查 package.json：确保分类正确

危险信号

反模式问题解决方案
typescript 放在 dependencies 中臃肿的生产环境移至 devDependencies
@types/* 放在 dependencies 中在生产环境中不必要移至 devDependencies
缺少依赖项的 @types没有类型安全将 @types 添加为 devDependency

常见的自我辩解

“我想全局使用 TypeScript”

实际情况：使用 npx tsc 运行项目的 TypeScript 版本。全局安装会导致版本不匹配。

“@types 应与运行时包保持一致”

实际情况：运行时包放在 dependencies 中，@types 放在 devDependencies 中。它们可以配合使用，但用途不同。

“对应用来说无关紧要”

实际情况：这样可以缩小 node_modules 的体积，并明确表达依赖项的用途。这是适用于所有项目的良好实践。

快速参考

包类型使用以下方式安装示例
TypeScript--save-devnpm i -D typescript
@types/*--save-devnpm i -D @types/node
运行时库--savenpm i lodash
库的类型--save-devnpm i -D @types/lodash

总而言之

TypeScript 和 @types 是开发工具。将它们安装为 devDependencies，可精简生产构建，并避免混淆哪些内容会在运行时运行。

参考资料

  • Dan Vanderkam 著，《Effective TypeScript》第 2 版
  • 条目 65：将 TypeScript 和 @types 放入 devDependencies

评论

支持 Markdown