napi-postinstall

The postinstall script helper for handling native bindings in npm versions affected by npm/cli#4828. This is a reimplementation of the node-install functionality from esbuild for napi-rs ecosystem packages like rollup, @swc/core and unrs-resolver.

For more details, please refer to the following issues:

• npm/cli#4828 -- root cause
• napi-rs/napi-rs#2569
• unrs/unrs-resolver#56

TOC

• Usage
  • TL;DR for package users
  • Notes for package authors
  • Install
  • Postinstall script
  • CLI
  • API
    • Types
    • Example
• Sponsors and Backers
  • Sponsors
  • Backers
• Changelog
• License

Usage

TL;DR for package users

You usually don't need to install napi-postinstall yourself — it is a postinstall helper used by some napi-rs packages.

• It works around npm/cli#4828, where npm can fail to install the correct platform-specific optional dependency.
• When it has to install a missing binding by itself, it uses the registry, credentials and CA settings from the project .npmrc, so private registries work without extra configuration. The file is read from the project that owns the installed package; one that only exists at a workspace root is not picked up yet, so keep a .npmrc next to that project. If npm itself cannot be queried, it warns and uses the public registry, which the two lookups done in JavaScript (reading a manifest and downloading a tarball) then fall back to.
• A binding that lives on another filesystem is copied rather than renamed. On Node before 16.15 that copy resolves relative symlinks, such as node_modules/.bin entries, against the source it then removes, so those links can break.
• pnpm and yarn resolve optional dependencies correctly in most cases, so the helper is usually a no-op there. Leaving install scripts enabled is the safe default.
• If your package manager warns about ignored build scripts, allow the build script for the dependency that needs it. For pnpm 10+, run pnpm approve-builds, or add that dependency (for example unrs-resolver, not napi-postinstall) to ignoredBuiltDependencies to silence the warning when installation already works.
• If the native binding fails to load, re-enable install scripts and reinstall.

Notes for package authors

Prefer a postinstall.js that calls the API instead of invoking the napi-postinstall binary from postinstall; see Postinstall script.

If your package runs napi-postinstall in postinstall, you can copy this note into your own README:

This package uses napi-postinstall so the correct native binding is installed on npm versions affected by npm/cli#4828. pnpm and yarn normally handle optional dependencies themselves; if your package manager reports ignored build scripts, you can allow the script or safely ignore it when the native binding already loads.

Install

# pnpm
pnpm add napi-postinstall

# yarn
yarn add napi-postinstall

# npm
npm i napi-postinstall

# bun
bun add napi-postinstall

Postinstall script

Prefer a postinstall.js that calls the API over invoking the CLI directly from postinstall. With npm --no-bin-links, the bin shim may not exist (unrs-resolver#190). Use a JavaScript file that calls the API instead:

// postinstall.js
const { checkAndPreparePackage } = require('napi-postinstall')

checkAndPreparePackage('unrs-resolver').catch(error => {
  console.error(error)
  process.exitCode = 1
})

{
  "scripts": {
    "postinstall": "node postinstall.js"
  }
}

This will check and prepare the napi binding packages for you automatically.

CLI

The CLI is available for manual use:

napi-postinstall unrs-resolver #<napi-package-name>

API

Types

// napi-postinstall
export interface PackageJson {
  name: string
  version: string
}

export declare function checkAndPreparePackage(
  packageNameOrPackageJson: PackageJson | string,
  checkVersion?: boolean,
): Promise<void>

// napi-postinstall/fallback
declare function fallback<T = unknown>(
  packageJsonPath: string,
  checkVersion?: boolean,
): T
export = fallback

The installed CLI script is also exposed as napi-postinstall/cli for use by the runtime fallback.

Example

// index.js
const { checkAndPreparePackage, isNpm } = require('napi-postinstall')

if (isNpm()) {
  void checkAndPreparePackage('unrs-resolver' /* <napi-package-name> */)
}

// fallback.js
module.exports = require('napi-postinstall/fallback')(
  require.resolve('./package.json') /* <napi-package-json-path> */,
  true /* <check-version> */,
)

Sponsors and Backers

Sponsors

1stG	RxTS	UnTS

Backers

1stG	RxTS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © JounQin@1stG.me