Back to Details

rust-npm-publish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rust npm Publishing

Rust 二进制文件发布至 npm

Distribute Rust binaries to npm using the 
optionalDependencies
platform package pattern.
使用
optionalDependencies
平台包模式将Rust二进制文件分发至npm。

When to Use This Skill

适用场景

Activate when any of the following are true:
  • Publishing Rust binaries to npm or debugging publish pipeline failures
  • Setting up 
    publish.config.ts
    , 
    bin.js
    , or platform package manifests
  • Managing version sync across workspace packages and 
    Cargo.toml
  • Working with 
    workspace:*
    protocol or prepare/restore scripts
  • Scripts matching 
    *publish*
    , 
    *platform*
    , 
    *version*
    , or 
    *sync*
    exist
当满足以下任一条件时启用：
  • 将Rust二进制文件发布到npm，或排查发布流水线失败问题
  • 配置
    publish.config.ts
    、
    bin.js
    或平台包清单
  • 管理工作区包与
    Cargo.toml
    之间的版本同步
  • 使用
    workspace:*
    协议或prepare/restore脚本
  • 存在匹配
    *publish*
    、
    *platform*
    、
    *version*
    或
    *sync*
    的脚本

Decision Tree

决策树

What does the user need?

Setting up publishing for the first time?
  → The Pattern section + Configuration + Templates

Running the publish pipeline?
  → Publish Pipeline section
  → Full details: references/publish-pipeline.md

Adding a new platform?
  → Adding a New Platform section
  → Platform reference: references/platform-matrix.md

Version sync / bump?
  → Versioning section
  → Full strategy: references/version-strategy.md
  → workspace:* details: references/workspace-protocol.md

Debugging a failure?
  → references/troubleshooting.md
用户需求是什么？

首次搭建发布流程？
  → 模式章节 + 配置 + 模板

执行发布流水线？
  → 发布流水线章节
  → 详细内容：references/publish-pipeline.md

新增平台支持？
  → 新增平台章节
  → 平台参考：references/platform-matrix.md

版本同步/更新？
  → 版本管理章节
  → 完整策略：references/version-strategy.md
  → workspace:*详情：references/workspace-protocol.md

排查失败问题？
  → references/troubleshooting.md

The Pattern

模式说明

@scope/my-tool                    ← main package (thin JS wrapper + bin.js)
├── optionalDependencies:
│   ├── @scope/my-tool-darwin-arm64   ← macOS ARM (M-series)
│   ├── @scope/my-tool-darwin-x64     ← macOS Intel
│   ├── @scope/my-tool-linux-x64      ← Linux x86_64
│   └── @scope/my-tool-windows-x64    ← Windows x86_64
Each platform package contains only the pre-compiled binary for that target. npm installs only the one matching the user's OS/CPU at install time.
Same approach used by SWC, Turbopack, esbuild, and similar tools.
@scope/my-tool                    ← 主包（轻量JS封装 + bin.js）
├── optionalDependencies:
│   ├── @scope/my-tool-darwin-arm64   ← macOS ARM（M系列）
│   ├── @scope/my-tool-darwin-x64     ← macOS Intel
│   ├── @scope/my-tool-linux-x64      ← Linux x86_64
│   └── @scope/my-tool-windows-x64    ← Windows x86_64
每个平台包仅包含对应目标平台的预编译二进制文件。npm会在安装时仅安装匹配用户操作系统/CPU的包。
该方法被SWC、Turbopack、esbuild等工具采用。

Configuration

配置

Each repo provides a 
publish.config.ts
(see examples/):
typescript
export default {
  scope: '@myorg',
  binaries: [{ name: 'my-cli', scope: 'cli', cargoPackage: 'my-cli-rs' }],
  platforms: ['darwin-x64', 'darwin-arm64', 'linux-x64', 'windows-x64'],
  mainPackages: [{ path: 'packages/cli', name: 'my-cli' }],
  cargoWorkspace: 'Cargo.toml',
  repositoryUrl: 'https://github.com/myorg/my-project',
};
每个仓库需提供
publish.config.ts
（参见examples/）：
typescript
export default {
  scope: '@myorg',
  binaries: [{ name: 'my-cli', scope: 'cli', cargoPackage: 'my-cli-rs' }],
  platforms: ['darwin-x64', 'darwin-arm64', 'linux-x64', 'windows-x64'],
  mainPackages: [{ path: 'packages/cli', name: 'my-cli' }],
  cargoWorkspace: 'Cargo.toml',
  repositoryUrl: 'https://github.com/myorg/my-project',
};

Publish Pipeline

发布流水线

sync-versions → generate-manifests → add-platform-deps → copy-binaries
→ validate-binaries → prepare-publish → validate-workspace → publish-platforms
→ wait-propagation → publish-main → restore-packages
Critical ordering: Platform packages MUST be published and propagated before main packages, because main packages reference them as 
optionalDependencies
.
See references/publish-pipeline.md for step-by-step details.
sync-versions → generate-manifests → add-platform-deps → copy-binaries
→ validate-binaries → prepare-publish → validate-workspace → publish-platforms
→ wait-propagation → publish-main → restore-packages
关键顺序：平台包必须在主包之前发布并完成同步，因为主包将它们作为
optionalDependencies
引用。
详细步骤参见references/publish-pipeline.md。

Main Package Wrapper (
bin.js
)

主包封装（bin.js）

The main npm package is a thin JS wrapper — 
bin.js
resolves the platform binary and spawns it. See templates/wrapper/ for the template.
Key details:
  • process.platform
    returns 
    win32
    (not 
    windows
    ) — map 
    win32-x64
    → 
    @scope/cli-windows-x64
  • Use 
    require.resolve('pkg/package.json')
    to find platform package, then read 
    main
    for binary name
  • Use 
    execFileSync
    and forward exit codes from the Rust process
  • Main package has NO 
    os
    /
    cpu
    fields — it installs everywhere. Only platform packages use those.
主npm包是一个轻量JS封装——
bin.js
负责解析平台二进制文件并启动它。模板参见templates/wrapper/。
核心细节：
  • process.platform
    返回
    win32
    （而非
    windows
    ）——需将
    win32-x64
    映射为
    @scope/cli-windows-x64
  • 使用
    require.resolve('pkg/package.json')
    查找平台包，然后读取
    main
    字段获取二进制文件名
  • 使用
    execFileSync
    并转发Rust进程的退出码
  • 主包不包含
    os
    /
    cpu
    字段——它可在所有环境安装。仅平台包使用这些字段。

Platform Package Manifests

平台包清单

Each platform package needs 
os
/
cpu
fields and a 
postinstall.js
for chmod:
json
{
  "name": "@scope/cli-darwin-arm64",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "main": "my-cli"
}
每个平台包需要
os
/
cpu
字段以及用于修改权限的
postinstall.js
：
json
{
  "name": "@scope/cli-darwin-arm64",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "main": "my-cli"
}

Platform Matrix

平台矩阵

PlatformRust Target
os
cpu
Binary Extension
darwin-arm64
aarch64-apple-darwin
darwin
arm64
(none)
darwin-x64
x86_64-apple-darwin
darwin
x64
(none)
linux-x64
x86_64-unknown-linux-gnu
linux
x64
(none)
windows-x64
x86_64-pc-windows-msvc
win32
x64
.exe
See references/platform-matrix.md for adding new platforms.
平台Rust 目标
os
cpu
二进制扩展名
darwin-arm64
aarch64-apple-darwin
darwin
arm64
无
darwin-x64
x86_64-apple-darwin
darwin
x64
无
linux-x64
x86_64-unknown-linux-gnu
linux
x64
无
windows-x64
x86_64-pc-windows-msvc
win32
x64
.exe
新增平台参见references/platform-matrix.md。

Adding a New Platform

新增平台支持

  1. Add to 
    platforms
    array in 
    publish.config.ts
  2. Add Rust target: 
    rustup target add <target-triple>
  3. Add to CI matrix in publish workflow
  4. Regenerate manifests: 
    pnpm tsx scripts/generate-platform-manifests.ts
  1. 在
    publish.config.ts
    的
    platforms
    数组中添加平台
  2. 添加Rust目标：
    rustup target add <target-triple>
  3. 在发布工作流的CI矩阵中添加平台
  4. 重新生成清单：
    pnpm tsx scripts/generate-platform-manifests.ts

Versioning

版本管理

Root 
package.json
is the single source of truth. Never manually edit version elsewhere.
root package.json (version: "0.2.15")
  ├── packages/cli/package.json  → 0.2.15  (via sync-versions.ts)
  ├── Cargo.toml                 → 0.2.15
  └── platform-packages/*/      → 0.2.15  (via generate-manifests)
根目录
package.json
是唯一版本数据源。切勿手动修改其他位置的版本号。
root package.json (version: "0.2.15")
  ├── packages/cli/package.json  → 0.2.15  (通过sync-versions.ts同步)
  ├── Cargo.toml                 → 0.2.15
  └── platform-packages/*/      → 0.2.15  (通过generate-manifests生成)

Version Sync Flow

版本同步流程

bash
npm version patch                     # Bump root: 0.2.15 → 0.2.16
pnpm tsx scripts/sync-versions.ts     # Propagate to all packages + Cargo.toml
bash
npm version patch                     # 更新根版本：0.2.15 → 0.2.16
pnpm tsx scripts/sync-versions.ts     # 同步至所有包 + Cargo.toml

Dev Builds

开发构建版本

CI computes: 
0.2.15
→ 
0.2.16-dev.{github_run_id}
Published with 
--tag dev
. Install: 
npm install my-cli@dev
Cargo.toml stays at base version (
0.2.15
) for dev builds — Cargo pre-release handling differs from npm.
CI会自动生成：
0.2.15
→ 
0.2.16-dev.{github_run_id}
使用
--tag dev
发布。安装命令：
npm install my-cli@dev
开发构建时，Cargo.toml保持基础版本（
0.2.15
）——Cargo的预发布版本处理逻辑与npm不同。

Version Bump Guide

版本更新指南

ChangeCommandExample
Breaking API
npm version major
1.0.0 → 2.0.0
New feature
npm version minor
0.2.0 → 0.3.0
Bug fix
npm version patch
0.2.15 → 0.2.16
CI/testingAutomatic (CI)0.2.15 → 0.2.16-dev.123
变更类型命令示例
破坏性API变更
npm version major
1.0.0 → 2.0.0
新增功能
npm version minor
0.2.0 → 0.3.0
Bug修复
npm version patch
0.2.15 → 0.2.16
CI/测试版本自动生成（CI）0.2.15 → 0.2.16-dev.123

workspace:* Protocol

workspace:*协议

pnpm uses 
workspace:*
for internal deps during development. Replace before publish, restore after:
bash
pnpm tsx scripts/prepare-publish.ts                  # Replace workspace:* → real versions
pnpm tsx scripts/validate-no-workspace-protocol.ts   # Safety gate
npm publish
pnpm tsx scripts/restore-packages.ts                 # Restore workspace:*
See references/workspace-protocol.md for details. See references/version-strategy.md for the full strategy.
pnpm在开发阶段使用
workspace:*
作为内部依赖标识。发布前需替换为实际版本，发布后恢复：
bash
pnpm tsx scripts/prepare-publish.ts                  # 将workspace:*替换为实际版本
pnpm tsx scripts/validate-no-workspace-protocol.ts   # 安全检查
npm publish
pnpm tsx scripts/restore-packages.ts                 # 恢复workspace:*
详情参见references/workspace-protocol.md。 完整策略参见references/version-strategy.md。

Troubleshooting Quick Reference

故障排查速查

ProblemLikely CauseFix
Unsupported platform
Missing platform in bin.jsAdd platform key mapping
Platform pkg not found on npmRegistry propagation delayWait; check publish logs
workspace:*
in published pkg		prepare-publish didn't runRun prepare-publish.ts
Binary not executablepostinstall didn't run
chmod +x
the binary
Version mismatchForgot to syncRun sync-versions.ts
See references/troubleshooting.md for detailed diagnostics.
问题可能原因修复方案
Unsupported platform
bin.js中缺少平台映射添加平台键映射
平台包在npm上找不到注册表同步延迟等待一段时间；检查发布日志
发布包中存在
workspace:*
未执行prepare-publish运行prepare-publish.ts
二进制文件无执行权限postinstall未运行执行
chmod +x
赋予二进制文件权限
版本不匹配忘记同步版本运行sync-versions.ts
详细诊断参见references/troubleshooting.md。

Templates

模板

DirectoryContents
templates/scripts/All 11 publish pipeline scripts
templates/wrapper/
bin.js
+ main package 
package.json
examples/Real 
publish.config.ts
from consuming projects
目录内容
templates/scripts/所有11个发布流水线脚本
templates/wrapper/
bin.js
+ 主包
package.json
examples/来自实际项目的
publish.config.ts
示例

Setup & Activation

安装与激活

bash
npx skills add -g onsager-ai/dev-skills --skill rust-npm-publish -a claude-code -y
Auto-activates when: 
publish.config.ts
present, scripts matching 
*publish*
or 
*platform*
exist, user mentions "publish", "platform packages", or "version sync".
bash
npx skills add -g onsager-ai/dev-skills --skill rust-npm-publish -a claude-code -y
自动激活条件：存在
publish.config.ts
、匹配
*publish*
或
*platform*
的脚本，或用户提及"publish"、"platform packages"、"version sync"。