README.md•6.72 kB
# napi-postinstall
[](https://github.com/un-ts/napi-postinstall/actions/workflows/ci.yml?query=branch%3Amain)
[](https://codecov.io/gh/un-ts/napi-postinstall)
[](https://github.com/plantain-00/type-coverage)
[](https://coderabbit.ai)
[](https://www.npmjs.com/package/napi-postinstall)
[](https://github.com/un-ts/napi-postinstall/releases)
[](https://conventionalcommits.org)
[](https://renovatebot.com)
[](https://standardjs.com)
[](https://github.com/prettier/prettier)
[](https://github.com/changesets/changesets)
The `postinstall` script helper for handling native bindings in legacy `npm` versions, this is a reimplementation of the [`node-install`][node-install] functionality from [`esbuild`][esbuild] for [`napi-rs`][napi-rs] ecosystem packages like [`rollup`][rollup], [`@swc/core`][swc-core] and [`unrs-resolver`][unrs-resolver].
For more details, please refer to the following issues:
- [npm/cli#4828](https://github.com/npm/cli/issues/4828) -- root cause
- [napi-rs/napi-rs#2569](https://github.com/napi-rs/napi-rs/issues/2569)
- [unrs/unrs-resolver#56](https://github.com/unrs/unrs-resolver/issues/56)
## TOC <!-- omit in toc -->
- [Usage](#usage)
- [Install](#install)
- [CLI](#cli)
- [API](#api)
- [Types](#types)
- [Example](#example)
- [Sponsors and Backers](#sponsors-and-backers)
- [Sponsors](#sponsors)
- [Backers](#backers)
- [Changelog](#changelog)
- [License](#license)
## Usage
### Install
```sh
# pnpm
pnpm add napi-postinstall
# yarn
yarn add napi-postinstall
# npm
npm i napi-postinstall
# bun
bun add napi-postinstall
```
### CLI
```sh
napi-postinstall unrs-resolver #<napi-package-name>
```
You can put it into `scripts#postinstall` of your `package.json`:
```json
{
"scripts": {
"postinstall": "napi-postinstall unrs-resolver"
}
}
```
This will check and prepare the napi binding packages for you automatically.
### API
#### Types
```ts
// 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
```
#### Example
```js
// 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
[](https://github.com/sponsors/JounQin)
### Sponsors
| 1stG | RxTS | UnTS |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [](https://opencollective.com/1stG) | [](https://opencollective.com/rxts) | [](https://opencollective.com/unts) |
### Backers
| 1stG | RxTS | UnTS |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [](https://opencollective.com/1stG) | [](https://opencollective.com/rxts) | [](https://opencollective.com/unts) |
## Changelog
Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.md).
## License
[MIT][] © [JounQin][]@[1stG.me][]
[node-install]: https://github.com/evanw/esbuild/blob/4475787eef4c4923b92b9fa37ebba1c88b9e1d9b/lib/npm/node-install.ts
[esbuild]: https://github.com/evanw/esbuild
[napi-rs]: https://github.com/napi-rs/napi-rs
[rollup]: https://github.com/rollup/rollup
[swc-core]: https://github.com/swc-project/swc
[unrs-resolver]: https://github.com/unrs/unrs-resolver
[1stG.me]: https://www.1stG.me
[JounQin]: https://github.com/JounQin
[MIT]: http://opensource.org/licenses/MIT