Package Exports

@wemt/npm-publish-easier
@wemt/npm-publish-easier/index.js

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 (@wemt/npm-publish-easier) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

NPM 发布助手 (npm-publish-easier)

简体中文 | English

一个增强 npm 包发布流程的自动化工具，支持智能构建、版本管理、文件复制和一键发布。

✨ 核心功能

🚀 一键初始化 - 通过 --init 命令快速创建项目配置文件
🧹 智能清理 - 通过 --clean 命令清理发布目录，保持工作环境整洁
🔒 灵活的发布目录配置 - 支持独立发布目录或当前目录发布，完全隔离开发环境
📦 智能文件复制 - 支持自定义复制规则，智能复制 LICENSE、README.md、docs 目录等必要文件
🔢 灵活版本管理 - 支持控制是否自动递增版本号，可独立进行版本更新
⚡ 多种发布模式 - 支持准备模式、版本递增模式、完整发布模式等多种工作流
🛡️ 可配置过滤 - 支持自定义过滤规则，自动过滤开发相关的 scripts 和 devDependencies
🔨 自定义构建 - 支持自定义构建命令，不局限于 rollup
⚙️ 完全配置驱动 - 基于用户配置文件运行，无硬编码默认值，适应各种项目结构
🌐 跨平台兼容 - 完美支持 Windows、macOS 和 Linux 系统

📦 安装

全局安装（推荐）

npm install -g @wemt/npm-publish-easier

本地安装

npm install --save-dev @wemt/npm-publish-easier

🚀 使用方法

基本用法

# 首次使用：创建配置文件
npm-publish-easier --init

# 清理发布目录
npm-publish-easier --clean

# 准备发布文件
npm-publish-easier

# 自动发布到 npm（包含版本递增）
npm-publish-easier -y

# 只递增版本号，不发布
npm-publish-easier --increment-version

# 准备发布文件但不递增版本号
npm-publish-easier --no-increment-version

# 使用自定义构建命令
npm-publish-easier --build-command "npm run build"

# 显示帮助信息
npm-publish-easier --help

在 package.json 中配置 scripts

{
  "scripts": {
    "publish": "npm-publish-easier -y",
    "publish:prepare": "npm-publish-easier",
    "publish:init": "npm-publish-easier --init",
    "publish:clean": "npm-publish-easier --clean",
    "version:bump": "npm-publish-easier --increment-version"
  }
}

然后使用：

npm run publish:init   # 创建配置文件
npm run publish:clean  # 清理发布目录
npm run publish        # 自动发布
npm run publish:prepare # 准备发布文件
npm run version:bump   # 仅递增版本号

📋 配置文件

快速开始

首次使用请先创建配置文件：

npm-publish-easier --init

这将在项目根目录创建 publish.config.js 配置文件，然后根据项目需要进行修改。

支持的配置文件

工具使用 publish.config.js 配置文件。

⚠️ 注意：配置文件是必需的，工具不会使用任何默认配置。

配置文件示例

使用 --init 命令创建的默认配置：

export default {
  // 自定义构建命令
  buildCommand: "npm run build",

  // 发布目录配置
  // "publish" - 在根目录下创建 publish 目录（默认）
  // "" - 直接在当前目录发布（不创建子目录）
  publishDir: "dist",

  // 自定义复制文件配置
  copyConfig: [
    {
      type: "file",
      source: "LICENSE",
      target: "LICENSE",
      description: "LICENSE",
    },
    {
      type: "file",
      source: "README.md",
      target: "README.md",
      description: "README.md",
    },
    {
      type: "dir",
      source: "docs",
      target: "docs",
      description: "docs directory",
    },
  ],

  // 自定义过滤配置
  filteredConfig: {
    scripts: ["publish", "test", "dev", "build"],
    devDependencies: ["@types/jest", "jest", "typescript", "rollup"],
  },
};

🔧 构建文件路径配置

重要说明： 构建输出路径必须与 publishDir 配置保持一致，或者通过 copyConfig 来处理构建文件的复制。

方案一：构建输出路径与 publishDir 一致（推荐）

如果你的构建工具（如 rollup、webpack、vite 等）输出到 dist 目录，那么 publishDir 也应该设置为 "dist"：

export default {
  // 构建命令输出到 dist 目录
  buildCommand: "npm run build", // 假设这个命令输出到 dist/

  // 发布目录设置为 dist，与构建输出一致
  publishDir: "dist",

  // 其他文件通过 copyConfig 复制到 dist 目录
  copyConfig: [
    {
      type: "file",
      source: "LICENSE",
      target: "LICENSE",
      description: "LICENSE 文件",
    },
    {
      type: "file",
      source: "README.md",
      target: "README.md",
      description: "README 文档",
    },
  ],
};

方案二：通过 copyConfig 复制构建文件

如果构建输出到其他目录（如 lib、build 等），可以通过 copyConfig 将构建文件复制到发布目录：

export default {
  buildCommand: "npm run build", // 输出到 lib/ 目录
  publishDir: "publish",

  copyConfig: [
    // 复制构建输出的文件
    {
      type: "dir",
      source: "lib", // 构建输出目录
      target: "lib", // 发布目录中的目标路径
      description: "构建输出文件",
    },
    // 复制其他必要文件
    {
      type: "file",
      source: "LICENSE",
      target: "LICENSE",
      description: "LICENSE 文件",
    },
  ],
};

方案三：直接在当前目录发布

如果构建直接输出到项目根目录，可以设置 publishDir 为空字符串：

export default {
  buildCommand: "npm run build", // 直接输出到根目录
  publishDir: "", // 在当前目录发布

  // 不需要复制构建文件，因为已经在正确位置
  copyConfig: [
    // 只需要复制其他必要文件（如果需要的话）
  ],
};

常见构建工具配置示例

Rollup 配置示例：

// rollup.config.js
export default {
  input: 'src/index.js',
  output: {
    file: 'publish/index.js',  // 直接输出到发布目录
    format: 'esm',
    banner: '#!/usr/bin/env node\n'  // CLI 工具需要的 shebang
  }
};

// publish.config.js
export default {
  buildCommand: "rollup -c",
  publishDir: "publish",  // 与 rollup 输出路径一致
  // ...
};

Webpack 配置示例：

// webpack.config.js
module.exports = {
  entry: "./src/index.js",
  output: {
    path: path.resolve(__dirname, "dist"), // 输出到 dist 目录
    filename: "bundle.js",
  },
};

// publish.config.js
export default {
  buildCommand: "webpack --mode=production",
  publishDir: "dist", // 与 webpack 输出路径一致
  // ...
};

📋 参数说明

参数	简写	说明
`--init`	-	创建初始配置文件
`--clean`	-	清理发布目录
`--yes`	`-y`	自动发布到 npm（包含版本递增）
`--increment-version`	-	强制递增版本号（不发布）
`--no-increment-version`	-	不递增版本号
`--build-command <cmd>`	-	自定义构建命令
`--help`	`-h`	显示帮助信息

参数优先级

命令行参数优先级最高
配置文件中的设置次之
默认设置优先级最低

⚠️ 注意事项

确保已登录 npm 账户：npm login
确保 package.json 中的 name 字段正确
首次发布需要确保包名没有被占用
重要： 构建输出路径必须与 publishDir 配置一致，或通过 copyConfig 处理构建文件复制
建议在发布前先测试：npm run publish:prepare
工具依赖构建工具进行构建，请确保构建配置正确
版本号遵循 semver 规范，仅自动递增 patch 版本
使用 --clean 命令会完全删除发布目录，请谨慎使用
工具具有完整的跨平台兼容性，在 Windows、macOS 和 Linux 上均可正常使用

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT

👨‍💻 作者

Mutaoinc & Wemt Team

如果这个工具对你有帮助，请给个 ⭐ Star 支持一下！