rust-npm-publish

Rust npm 公開

optionalDependencies のプラットフォームパッケージパターンを使用して、Rust バイナリを npm で配布します。

このスキルを使用するタイミング

次のいずれかに該当する場合に有効化します。

• Rust バイナリを npm で公開する場合、または公開パイプラインの失敗をデバッグする場合
• publish.config.ts、bin.js、またはプラットフォームパッケージのマニフェストを設定する場合
• ワークスペースパッケージと Cargo.toml のバージョン同期を管理する場合
• workspace:* プロトコルまたは prepare／restore スクリプトを扱う場合
• *publish*、*platform*、*version*、または *sync* に一致するスクリプトが存在する場合

判断ツリー

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

パターン

@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

各プラットフォームパッケージに含まれるのは、そのターゲット向けにコンパイル済みのバイナリのみです。npm は、インストール時にユーザーの OS／CPU に一致するものだけをインストールします。

SWC、Turbopack、esbuild などで使われているものと同じアプローチです。

設定

各リポジトリには publish.config.ts が用意されています（examples/ を参照）。

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',
};

公開パイプライン

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 を参照してください。

メインパッケージのラッパー（bin.js）

メインの npm パッケージは薄い JS ラッパーです。bin.js がプラットフォームバイナリを解決し、起動します。テンプレートについては templates/wrapper/ を参照してください。

主なポイント：

• process.platform が返すのは windows ではなく win32 です。win32-x64 を @scope/cli-windows-x64 にマッピングします。
• require.resolve('pkg/package.json') を使用してプラットフォームパッケージを探し、次に main を読み込んでバイナリ名を取得します。
• execFileSync を使用し、Rust プロセスの終了コードを引き継ぎます。
• メインパッケージには os／cpu フィールドがありません。どこにでもインストールされます。これらのフィールドを使用するのはプラットフォームパッケージのみです。

プラットフォームパッケージのマニフェスト

各プラットフォームパッケージには、os／cpu フィールドと chmod 用の postinstall.js が必要です。

{
  "name": "@scope/cli-darwin-arm64",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "main": "my-cli"
}

プラットフォームマトリックス

プラットフォーム	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 を参照してください。

新しいプラットフォームの追加

1. publish.config.ts の platforms 配列に追加します
2. Rust ターゲットを追加します：rustup target add <target-triple>
3. 公開ワークフローの CI マトリックスに追加します
4. マニフェストを再生成します：pnpm tsx scripts/generate-platform-manifests.ts

バージョン管理

ルートの package.json が唯一の信頼できる情報源です。他の場所でバージョンを手動編集しないでください。

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)

バージョン同期の流れ

npm version patch                     # Bump root: 0.2.15 → 0.2.16
pnpm tsx scripts/sync-versions.ts     # Propagate to all packages + Cargo.toml

開発ビルド

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 と異なるためです。

バージョン更新ガイド

変更	コマンド	例
互換性を損なう API 変更	npm version major	1.0.0 → 2.0.0
新機能	npm version minor	0.2.0 → 0.3.0
バグ修正	npm version patch	0.2.15 → 0.2.16
CI／テスト	自動（CI）	0.2.15 → 0.2.16-dev.123

workspace:* プロトコル

pnpm は開発中の内部依存関係に workspace:* を使用します。公開前に置換し、公開後に元に戻します。

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:*

詳細は references/workspace-protocol.md を参照してください。戦略の全容については references/version-strategy.md を参照してください。

トラブルシューティングの早見表

問題	考えられる原因	解決方法
Unsupported platform	bin.js にプラットフォームが登録されていません	プラットフォームのキーとマッピングを追加します
プラットフォームのパッケージが npm で見つからない	レジストリへの反映が遅れています	しばらく待ち、公開ログを確認します
公開済みパッケージに workspace:* が含まれている	prepare-publish が実行されませんでした	prepare-publish.ts を実行します
バイナリに実行権限がない	postinstall が実行されませんでした	バイナリに chmod +x を実行します
バージョンが一致しない	同期を忘れています	sync-versions.ts を実行します

詳しい診断については、references/troubleshooting.md を参照してください。

テンプレート

ディレクトリ	内容
templates/scripts/	公開パイプラインの全 11 スクリプト
templates/wrapper/	bin.js とメインパッケージの package.json
examples/	利用側プロジェクトの実際の publish.config.ts

セットアップと有効化

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」に言及する。