NPM Build Script Allowlist

0.20250131.0 · active · verified Tue Apr 21

This package provides a curated, manually maintained list of common npm packages that legitimately require build scripts (e.g., `preinstall`, `install`, `postinstall`) to function correctly during installation. Its primary purpose is to enhance supply chain security by enabling package managers like pnpm v10 and Bun (which block build scripts by default) to differentiate between necessary and potentially malicious build script executions. The package uses a date-based versioning scheme (e.g., `0.YYYYMMDD.0`) to indicate the last update date, facilitating easy identification of outdated lists. Currently, it is primarily integrated with pnpm v10 via the `onlyBuiltDependenciesFile` and `configDependencies` fields in `package.json`. While efforts are underway to support other package managers through `@lavamoat/allow-scripts`, its current utility is specific to pnpm's security model. The list is not exhaustive, focusing on widely used packages whose build scripts are deemed essential, and requires manual maintenance and updates by users to stay current and effective. It provides a community-driven approach to maintaining a secure dependency graph where build scripts are an unavoidable necessity.

Common errors

```
Build script was run for [package-name] which is not in the allowlist. To allow it, add it to the 'onlyBuiltDependenciesFile'.
```
cause A dependency required a build script, but it was not present in the `common.json` allowlist, the allowlist being used is outdated, or the package is simply not included.

fix First, verify that the `build-scripts-allowlist` configuration in your `package.json` (version and hash) is up-to-date with the latest from the GitHub repository. If the issue persists, and you believe the package should be allowed, consider opening an issue or pull request on the `build-scripts-allowlist` GitHub to propose its inclusion.
```
Error: ENOENT: no such file or directory, stat 'node_modules/.pnpm-config/build-scripts-allowlist/common.json'
```
cause The `onlyBuiltDependenciesFile` path in `package.json` is incorrect, or the `build-scripts-allowlist` package was not installed correctly (e.g., missing from `dependencies`).

fix Double-check the `onlyBuiltDependenciesFile` path in your `package.json` against the example in the README. Ensure `build-scripts-allowlist` is listed in your project's `dependencies` and that `pnpm install` was run successfully after configuring `configDependencies`.

Warnings

breaking This package currently *only* supports PNPM v10 directly. Integration with other package managers like npm or Yarn is not directly available, although future support through `@lavamoat/allow-scripts` is planned.
Fix: If not using PNPM v10, this package cannot be directly utilized for build script allowlisting. Consider alternative security measures or await broader package manager support.
gotcha The `build-scripts-allowlist` package utilizes a date-based versioning scheme and requires users to manually specify the exact version and integrity hash in their `package.json` `pnpm.configDependencies` field. This hash is crucial for security and must be updated regularly from the package's GitHub repository.
Fix: Always refer to the official GitHub repository's README for the latest version number and integrity hash, and update your `package.json` configuration accordingly to ensure you are using the most secure and up-to-date allowlist.
gotcha The allowlist provided by this package is manually maintained and not exhaustive. It only includes common packages with essential build scripts and cannot guarantee protection against all supply chain attacks or ensure completeness. A package that should be allowed might be missing, or a compromised package could be included.
Fix: Report missing packages or potential issues via GitHub issues/pull requests. Users are encouraged to review their dependency trees and understand the build script requirements of their project's specific dependencies, augmenting the allowlist with their own findings if necessary.
gotcha The effectiveness of this allowlist relies entirely on the package manager's feature to block build scripts by default (e.g., PNPM 10's `onlyBuiltDependencies` feature). Without this underlying security mechanism, the allowlist provides no inherent protection.
Fix: Ensure your package manager is configured to block build scripts by default and utilize this allowlist as an exception mechanism. Verify that `onlyBuiltDependencies` is enabled in your pnpm configuration.

Install

npm install build-scripts-allowlist npm
yarn add build-scripts-allowlist yarn
pnpm add build-scripts-allowlist pnpm

Imports

build-scripts-allowlist

This package does not export any JavaScript/TypeScript symbols for direct programmatic import. It is intended to be consumed as a configuration file by package managers like pnpm.

This package is a data file for package manager configuration, not a library for programmatic JS/TS use.

Quickstart

This `package.json` snippet demonstrates how to configure pnpm v10 to utilize `build-scripts-allowlist` for securely managing allowed build scripts. It specifies the exact version and integrity hash for security and points to the `common.json` file.

{
  "name": "my-project",
  "version": "1.0.0",
  "pnpm": {
    "configDependencies": {
      "build-scripts-allowlist": "0.20250131.0+sha512-jog/QKpjOZlMn5wpzrCLjOVkD65jigLQEX86yJdBKxUOPnFjAYlETBhILVVD6UpYFt1WVbHEy8uDYnoE5hWldg==" 
    },
    "onlyBuiltDependenciesFile": "node_modules/.pnpm-config/build-scripts-allowlist/common.json"
  },
  "dependencies": {
    "build-scripts-allowlist": "^0.20250131.0" 
  }
}
// NOTE: The version and SHA512 hash for 'build-scripts-allowlist' in 'configDependencies' MUST be updated 
// regularly from the latest official GitHub README to ensure security and currency.
// The 'dependencies' entry simply installs the package so its data file is available.

view raw JSON →