npm Installer

since 0.0.6

This provides a tarball containing an npm package (npm-package.tar.gz) which when installed into an npm project: detects the current platform, fetches the best possible archive from your artifact URL, and copies the binary into your node_modules. This can be used to install the binaries like any other npm package, or to run them with npx.

This kind of installer is ideal for making a native Rust tool available to JS devs.

An "installer hint" will be provided that shows how to install via npm like so:

npm install @axodotdev/[email protected]

cargo-dist does not publish the package for you, you need to do that manually once the tarball is built. Conveniently, npm supports publishing from a url-to-a-tarball directly, and since 0.0.7 we make our tarballs look like "proper" npm package tarballs, so you can just do this:

npm publish URL_TO_TARBALL

You can find the URL to the tarball at the bottom of the Github Release, inside the collapsible "assets" dropdown (*-npm-package.tar.gz). The format of the url is:

<repo>/releases/download/<tag>/<app-name>-npm-package.tar.gz

Example:

https://github.com/axodotdev/oranda/releases/download/v0.0.3/oranda-npm-package.tar.gz

If you're cutting a stable release (not-prerelease), you can use the "latest" URL format:

https://github.com/axodotdev/oranda/releases/latest/download/oranda-npm-package.tar.gz

In the future we may introduce more streamlined CI-based publishing workflows.

You can set the @scope the package is published under with the npm-scope cargo-dist config.

We will otherwise do our best to faithfully translate any standard Cargo.toml values you set to an equivalent in the npm package.json format (name, version, authors, description, homepage, repository, keywords, categories...).

The package will also include an npm-shrinkwrap.json file for the npm packages the installer uses, this is the same as package-lock.json but "really for reals I want this to be respected even if it's installed into another project". Note that cargo install similarly disrespects Cargo.lock unless you pass --locked.

Limitations and Caveats

• Requires a well-defined artifact URL
• Cannot detect situations where musl-based builds are appropriate (static or dynamic)
• Relies on nodejs's builtin gzip support to unpack the files, which only works with .tar.gz
• Cannot run any kind of custom install logic

As a result of the .tar.gz limitation, cargo dist init will prompt you to change windows-archive and unix-archive to ".tar.gz" if you enable the npm installer, erroring if you decline.