@viso/package-publish

一个专为 npm 包发布流程设计的工具，用于自动处理发布前后的 package.json 字段调整和恢复操作。

功能特性

• 🔄 自动处理发布前的 package.json 字段调整
• 📦 支持 main、module、types 字段的智能替换
• 🛡️ 发布后自动恢复原始配置
• 💾 安全的缓存机制保护原始文件
• 🧹 自动清理临时缓存文件
• 🎯 专为 TypeScript 项目优化

安装

npm install @viso/package-publish

使用场景

在 TypeScript 项目中，开发时通常使用 src/index.ts 作为入口文件，但发布到 npm 时需要指向编译后的文件。这个工具可以自动处理这种转换。

开发时的 package.json

{
  "main": "src/index.ts",
  "module": "src/index.ts", 
  "types": "src/index.ts"
}

发布时自动调整为

{
  "main": "lib/index.js",
  "module": "es/index.js",
  "types": "es/index.d.ts"
}

命令行使用

发布前处理

# 在发布前调整 package.json 字段
npx package-publish --before

该命令会：

1. 备份原始 package.json 到 node_modules/.cache/package.json
2. 将 src/index.ts 替换为相应的编译文件路径：
   • main: src/index.ts → lib/index.js
   • module: src/index.ts → es/index.js
   • types: src/index.ts → es/index.d.ts

发布后恢复

# 在发布后恢复原始 package.json
npx package-publish --after

该命令会：

1. 从缓存中恢复原始的字段值
2. 移除 npm 自动添加的 gitHead 字段
3. 清理缓存文件

完整发布流程

# 1. 构建项目
npm run build

# 2. 发布前处理
npx package-publish --before

# 3. 执行发布
npm publish

# 4. 发布后恢复
npx package-publish --after

API 使用

beforePublish

发布前处理函数：

import { beforePublish } from '@viso/package-publish'

// 处理指定路径的 package.json
await beforePublish('/path/to/package.json')

// 处理当前项目的 package.json
await beforePublish('./package.json')

postPublish

发布后恢复函数：

import { postPublish } from '@viso/package-publish'

// 恢复指定路径的 package.json
await postPublish('/path/to/package.json')

// 恢复当前项目的 package.json
await postPublish('./package.json')

readJson

读取并解析 JSON 文件：

import { readJson } from '@viso/package-publish'

// 读取 package.json
const packageJson = await readJson<any>('./package.json')

// 类型安全的读取
interface PackageJson {
  name: string
  version: string
  main?: string
  module?: string
  types?: string
}

const pkg = await readJson<PackageJson>('./package.json')

集成到 npm scripts

在 package.json 中添加发布脚本：

{
  "scripts": {
    "prepublishOnly": "npm run build && package-publish --before",
    "postpublish": "package-publish --after",
    "publish:safe": "npm run prepublishOnly && npm publish && npm run postpublish"
  }
}

使用 prepublishOnly 和 postpublish 钩子

{
  "scripts": {
    "build": "package-build --module --tsc",
    "prepublishOnly": "package-publish --before",
    "postpublish": "package-publish --after"
  }
}

然后只需要运行：

npm publish

npm 会自动执行 prepublishOnly → publish → postpublish 的完整流程。

缓存机制

工具使用 node_modules/.cache/ 目录来临时存储原始的 package.json：

project/
├── package.json          # 当前的 package.json
├── node_modules/
│   └── .cache/
│       └── package.json  # 备份的原始文件
└── src/
    └── index.ts

字段转换规则

| 原始值 | 转换后值 | |--------|----------| | src/index.ts (main) | lib/index.js | | src/index.ts (module) | es/index.js | | src/index.ts (types) | es/index.d.ts | | 其他值 | 保持不变 |

错误处理

• 如果缓存文件不存在，恢复操作会跳过相应字段
• 如果 JSON 解析失败，会抛出详细的错误信息
• 如果文件读取失败，会返回 undefined

依赖项

• commander: 命令行参数解析
• fs-extra: 增强的文件系统操作

许可证

本项目使用 MIT 许可证。