package.json

基本配置

{
  "name": "@your-scope/your-package",  // 包名（推荐使用scope）
  "version": "1.0.0",                 // 遵循语义化版本（SemVer）
  "description": "Your package description",
  "keywords": ["react", "component", "library"],
  "author": "Your Name <email@example.com>",
  "license": "MIT",                   // 开源协议（MIT/ISC/Apache等）
}

入口文件配置

定义不同模块系统的入口，确保兼容性：

{
  // CommonJS 入口（Node.js）
  "main": "./dist/cjs/index.js",

  // ES Module 入口（现代打包工具）
  "module": "./dist/esm/index.js",

  // TypeScript 类型声明（必须）
  "types": "./dist/types/index.d.ts",

  // 现代导出语法（优先级高于 main/module，推荐）
  "exports": {
    ".": {
      "require": "./dist/cjs/index.js", // CommonJS
      "import": "./dist/esm/index.js",  // ES Module
      "types": "./dist/types/index.d.ts"
    },
    "./styles.css": "./dist/styles.css" // 子路径导出
  },

  // 浏览器环境专用入口（可选）
  "browser": "./dist/umd/index.min.js"
}

模块系统支持

{
  // 标记是否使用 ES Module（若源码为 ESM 需设置）
  "type": "module",

  // 标识无副作用（方便 Tree Shaking）
  "sideEffects": false,

  // 指定针对浏览器的兼容性（影响Babel转译）
  "browserslist": [
    ">0.2%",
    "not dead",
    "not op_mini all"
  ]
}

依赖管理

{
  "dependencies": {}, // 组件库通常无 runtime 依赖

  // 宿主环境依赖（避免重复安装）
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },

  // 开发依赖（测试、构建工具等）
  "devDependencies": {
    "typescript": "^5.0.0",
    "rollup": "^4.0.0",
    "@testing-library/react": "^14.0.0"
  },

  // 可选依赖（某些功能的按需加载）
  "optionalDependencies": {}
}

发布配置

控制 npm 发包内容和权限：

{
  // 包含的文件白名单（防止发布多余文件）
  "files": [
    "dist",          // 编译后的代码
    "types",         // 类型声明文件
    "README.md",
    "LICENSE"
  ],

  // 私有包标记（必须为 false）
  "private": false,

  // 发布配置（如使用组织包或公开访问）
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

脚本命令

常用开发脚本示例：

{
  "scripts": {
    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
    "build:cjs": "tsc --module commonjs --outDir dist/cjs",
    "build:esm": "tsc --module esnext --outDir dist/esm",
    "build:types": "tsc --emitDeclarationOnly --outDir dist/types",
    "prepublishOnly": "npm run build && npm test", // 自动构建保障发包安全
    "test": "jest",
    "lint": "eslint src",
    "format": "prettier --write src"
  }
}

工程化集成

增强开发体验的配置：

{
  // Husky 提交钩子
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },

  // 提交时自动格式化
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"]
  },

  // Monorepo 支持（可选）
  "workspaces": ["packages/*"]
}

类型补充

增强 IDE 支持的配置（非必需）：

{
  "typesVersions": {
    "*": {
      "*": ["./dist/types/*"]
    }
  }
}

关键注意事项

1. 入口优先级：exports > module/main，现代库推荐使用 exports 定义多入口
2. Tree Shaking：需同时满足 sideEffects:false + ES Module 格式
3. 样式处理：若包含 CSS，需在 files 中添加并设置 sideEffects: ["*.css"]
4. 版本约定：peerDependencies 建议使用宽松版本范围（如 >=16.8.0）
5. 构建策略：推荐同时输出 ESM 和 CJS 格式，TypeScript 库必须发布类型声明