bcryptjs

library2.4.3jsnpmunverified

bcryptjs is an optimized bcrypt implementation in pure JavaScript with zero dependencies. It provides an API compatible with the native C++ `bcrypt` module but ensures maximum portability across Node.js and browser environments without requiring compilation tools like `node-gyp`. While highly convenient and stable, the pure JS implementation is roughly 30% slower than the native binding.

auth-security serialization

npm install bcryptjs

github ↗package ↗

INSTALL

IMPORT

SIG · BCRYPTJS

bcryptjs

auth-securityjavascriptv2.4.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bcrypt

✓ import bcrypt from 'bcryptjs'; // ES Modules const bcrypt = require('bcryptjs'); // CommonJS

✗ import { hash, compare } from 'bcryptjs'; // Named imports can fail depending on the bundler/environment as it is primarily a CommonJS export.

Always import the default object and call methods on it. For TypeScript environments, ensure you also install the community type definitions (`@types/bcryptjs`).

This quickstart demonstrates the standard, secure way to hash a password with a generated salt, and then securely compare a plaintext login attempt against the stored hash using asynchronous methods.

import bcrypt from 'bcryptjs'; async function handlePassword() { const plainTextPassword = 'mySuperSecretPassword123!'; const saltRounds = 10; try { // 1. Generate a salt and hash the password (Async) const salt = await bcrypt.genSalt(saltRounds); const hashedPassword = await bcrypt.hash(plainTextPassword, salt); console.log('Hashed:', hashedPassword); // 2. Compare a login attempt with the hashed password (Async) const loginAttempt = 'mySuperSecretPassword123!'; const isMatch = await bcrypt.compare(loginAttempt, hashedPassword); if (isMatch) { console.log('Authentication successful!'); } else { console.log('Invalid credentials.'); } } catch (error) { console.error('Error during hashing/comparison:', error); } } handlePassword();

Debug

Known issues

breakingUsing synchronous methods (`hashSync`, `compareSync`, `genSaltSync`) in a Node.js server environment blocks the entire main event loop.

fix

Always use the asynchronous methods (`hash`, `compare`, `genSalt`) returning Promises or accepting callbacks in server-side code to prevent DoS-like freezes under load.

affects: All

gotchaThe bcrypt algorithm has a strict 72-byte limit on the input password string. Any characters beyond the 72nd byte are silently truncated and ignored during hashing and comparison.

fix

If your application needs to support extremely long passwords or multi-byte characters that exceed 72 bytes, pre-hash the password using a fast cryptographic hash (like SHA-256 or SHA-512) before passing it to `bcryptjs`.

affects: All

gotchaBecause `bcryptjs` is written in pure JavaScript, it is computationally slower (~30%) than the native C++ `bcrypt` module. A high salt round (e.g., 14+) will take significantly longer to compute.

fix

Balance security and performance by selecting an appropriate salt round cost (typically 10 to 12 for modern web applications). If performance is a critical bottleneck, migrate to the native `bcrypt` package.

affects: All

Errors

Common errors & fixes

TS7016: Could not find a declaration file for module 'bcryptjs'.

The `bcryptjs` library is written in JavaScript and does not bundle TypeScript declaration (`.d.ts`) files natively.

fix

Install the community-maintained DefinitelyTyped definitions by running `npm install --save-dev @types/bcryptjs` or `yarn add -D @types/bcryptjs`.

Server freezes or times out during traffic spikes (No explicit error thrown).

The server is likely using `bcrypt.compareSync()` or `bcrypt.hashSync()` during user authentication/registration. Because hashing is computationally expensive by design, synchronous calls block the Node.js event loop, preventing the server from handling other concurrent requests.

fix

Refactor the authentication logic to use `await bcrypt.compare(password, hash)` and `await bcrypt.hash(password, salt)`.

Error: Illegal arguments: string, undefined (or object)

This usually occurs when passing an undefined or incorrectly typed variable to `bcrypt.compare(plaintext, hash)`. The `hash` parameter might be missing if the database lookup failed and the developer didn't check if the user object exists before comparing passwords.

fix

Ensure both arguments passed to `bcrypt.compare()` are valid strings. Always check if the user and their stored hashed password exist before attempting a comparison: `if (!user || !user.passwordHash) return false;`.

Upgrade

Version history

2.4.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

51 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dcodeIO/bcrypt.js ↗

packagehttps://www.npmjs.com/package/bcryptjs ↗