rust-npm-publish

Rust npm Publishing

Distribute Rust binaries to npm using the optionalDependencies platform package pattern.

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

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

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.

Configuration

Each repo provides a publish.config.ts (see 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',
};