bcrypt.js Password Hashing

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ES Module context (e.g., in a modern Node.js project with `"type": "module"` or a browser module).
  fix Update your import statement from `const bcrypt = require('bcryptjs')` to `import bcrypt from 'bcryptjs'`.

• Error: data and salt arguments required by bcrypt.hash.

  cause `bcrypt.hash` was called with an insufficient number of arguments, typically missing the `salt` or `rounds` parameter.
  fix Ensure `bcrypt.hash` is called with at least two arguments: the password (`data`) and either a generated `salt` or the number of `rounds` for salt generation (e.g., `bcrypt.hash(password, 10)`).

• TypeError: Cannot read properties of undefined (reading 'then')

  cause This usually occurs when attempting to `await` or `.then()` on an `bcrypt` asynchronous function (like `bcrypt.hash`) that returned `undefined` because it was called with an incorrect number of arguments, implicitly switching it to a callback-based API (if applicable) or failing to return a promise.
  fix Verify that asynchronous `bcrypt` functions are called with the correct arguments to return a promise (e.g., `await bcrypt.hash(password, 10)`) or, if using callbacks, that the callback is correctly provided (e.g., `bcrypt.hash(password, 10, (err, hash) => {})`).

Warnings

• breaking Since v3.0.0, bcrypt.js exports an ECMAScript module (ESM) by default. Projects using CommonJS `require()` will need to update to `import` syntax or configure their bundler/Node.js environment accordingly.
  Fix: Update `require()` statements to `import bcrypt from 'bcryptjs'`.
• breaking Version 3.0.0 changed the default hash generation to produce 2b-style hashes. While this library was not affected by the original 2a/2b bug, the output format for newly generated hashes has changed.
  Fix: Ensure any systems expecting a specific bcrypt version (e.g., 2a) are compatible with 2b hashes or adjust accordingly.
• gotcha As a pure JavaScript implementation, `bcryptjs` is approximately 30% slower than the native C++ bcrypt binding available on Node.js. This affects the number of iterations that can be processed in a given time.
  Fix: Account for performance differences by potentially reducing the number of bcrypt rounds or using the C++ binding (`bcrypt`) for performance-critical Node.js applications.
• gotcha The maximum input password length for bcrypt.js is 72 bytes. Passwords exceeding this length are not implicitly truncated or validated by the library itself.
  Fix: Implement explicit password length checks in your application code, using `bcrypt.truncates(password)` if necessary, before passing to hashing functions.
• gotcha When using the ESM variant of bcrypt.js directly in a browser without a bundler, the `crypto` import may need to be stubbed out (e.g., via an import map) to prevent browser-specific errors.
  Fix: Use a bundler (like Webpack, Rollup, Vite) or configure an import map in your HTML to stub out the `crypto` module.

Install

• npm install bcryptjs npm
• yarn add bcryptjs yarn
• pnpm add bcryptjs pnpm

Imports

• bcrypt
  wrong:

  const bcrypt = require('bcryptjs')

  correct:

  import bcrypt from 'bcryptjs'

  ESM-first by default since v3.0.0, although a UMD fallback is provided.

Quickstart

Hashes a password with an automatically generated salt (10 rounds) and then demonstrates how to compare a password against the stored hash using the asynchronous API.

import bcrypt from "bcryptjs";

async function main() {
  const password = "mySecretPassword123";
  // Auto-generate a salt with 10 rounds and hash the password
  const hash = await bcrypt.hash(password, 10);
  console.log("Hashed password:", hash);

  // Compare a password against the stored hash
  const isMatch = await bcrypt.compare(password, hash);
  console.log("Password matches:", isMatch); // true

  const notMatch = await bcrypt.compare("wrongPassword", hash);
  console.log("Wrong password matches:", notMatch); // false
}
main();