Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
hooks
✓ import hooks from 'libnpmhook';
✗ import { hooks } from 'libnpmhook';
The library exports a single default object containing all API methods.
hooks (CommonJS)
✓ const hooks = require('libnpmhook');
✗ const { add, ls } = require('libnpmhook');
CommonJS usage also accesses the default export object, not named exports directly from the module root.
add
✓ import hooks from 'libnpmhook'; hooks.add(...);
✗ import { add } from 'libnpmhook'; add(...);
Access methods like `add`, `rm`, `ls`, `update` as properties of the `hooks` object.
Demonstrates how to add, list, and remove an npm registry hook for a package, including necessary authentication and OTP handling.
import hooks from 'libnpmhook';
async function manageNpmHooks() {
// Generate a unique package name for example purposes
const packageName = 'example-package-' + Math.random().toString(36).substring(7);
const endpointUrl = 'https://example.com/webhook-receiver'; // Replace with your actual endpoint
const secret = 'superSecretKey123'; // Replace with a strong, unique secret
const authToken = process.env.NPM_TOKEN ?? ''; // Set NPM_TOKEN env var with your npm automation token
const otpCode = process.env.NPM_OTP ?? ''; // Optional: set NPM_OTP env var if 2FA is enabled
if (!authToken) {
console.error("Error: NPM_TOKEN environment variable is not set. Please provide an npm automation token.");
return;
}
try {
console.log(`Attempting to add a hook for package: ${packageName}`);
const addedHook = await hooks.add(packageName, endpointUrl, secret, {
token: authToken,
otp: otpCode // OTP might be required if 2FA is enabled on your account
});
console.log('Successfully added hook:', addedHook);
console.log(`
Listing all hooks for package: ${packageName}`);
const packageHooks = await hooks.ls(packageName, { token: authToken });
console.log(`Hooks found for ${packageName}:`, packageHooks);
// Clean up: Remove the created hook
if (addedHook && addedHook.id) {
console.log(`
Removing hook with ID: ${addedHook.id}`);
await hooks.rm(addedHook.id, { token: authToken, otp: otpCode });
console.log('Hook removed successfully.');
}
} catch (error) {
console.error('Error managing npm hooks:', error.message);
if (error.code === 'EOTP') {
console.error('A One-Time Password (OTP) is required for this operation. Please set NPM_OTP environment variable.');
} else if (error.code === 'E401' || error.code === 'E403') {
console.error('Authentication failed. Check your NPM_TOKEN and permissions.');
}
}
}
manageNpmHooks();
Debug
Known issues
breakinglibnpmhook requires Node.js versions ^18.17.0 || >=20.5.0. Older Node.js environments are not supported and will result in errors.fixUpgrade your Node.js runtime to version 18.17.0 or newer, or 20.5.0 or newer.
affects: <18.17.0, <20.5.0
gotchaAll operations interacting with the npm registry require authentication. Failing to provide a valid `opts.token` will result in E401 Unauthorized or E403 Forbidden errors.fixEnsure `opts.token` is provided with an npm automation token for all registry operations. For publishing-related hooks, this token typically requires write permissions.
affects: >=1.0.0
gotchaCertain operations, especially those involving sensitive changes (like adding/removing hooks for a package or scope owned by a 2FA-enabled account), may require a One-Time Password (OTP). If an operation fails with `err.code === 'EOTP'`, you must retry the request with `opts.otp` set to the current OTP.fixCatch errors and check for `err.code === 'EOTP'`. If encountered, prompt the user for their OTP and retry the request including `{otp: <2fa token>}` in the options. affects: >=1.0.0
gotchaAll API methods return Promises. Forgetting to `await` or handle the promise (`.then()/.catch()`) will lead to unhandled promise rejections and unexpected behavior.fixAlways use `await` with `async` functions or explicitly handle returned Promises with `.then()` and `.catch()` blocks.
affects: >=1.0.0
Errors
Common errors & fixes
Error: E401 Unauthorized
Missing or invalid authentication token provided in options.
fixProvide a valid npm automation token via `opts.token` for all registry operations. Check your token's permissions and expiry.
Error: EOTP
The requested operation requires a One-Time Password because the account has two-factor authentication enabled.
fixRetry the operation, including `{otp: '<your-6-digit-otp>'}` in the options object. TypeError: hooks.add is not a function
Attempting to destructure methods from the module directly instead of accessing them via the default exported 'hooks' object.
fixEnsure you are importing the default export: `import hooks from 'libnpmhook';` or `const hooks = require('libnpmhook');` and then call `hooks.add(...)`. Error: Cannot find module 'libnpmhook'
The package is not installed or the import/require path is incorrect.
fixRun `npm install libnpmhook` to add the package to your project dependencies.
Audit
Dependencies
npm-registry-fetchrequiredUsed internally for all registry interactions; all options are passed through directly to this library.