From 1e2617f4214e154e2f54da1c918d3211ca4257e9 Mon Sep 17 00:00:00 2001
From: Paul Valladares <85648028+dreyfus92@users.noreply.github.com>
Date: Tue, 28 Apr 2026 19:49:37 -0500
Subject: [PATCH 1/2] feat(preferred): add `bcrypt` replacements and docs

---
 docs/modules/bcrypt.md   | 39 +++++++++++++++++++++++++++++++++++++++
 manifests/preferred.json | 11 +++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docs/modules/bcrypt.md

diff --git a/docs/modules/bcrypt.md b/docs/modules/bcrypt.md
new file mode 100644
index 0000000..3d0145b
--- /dev/null
+++ b/docs/modules/bcrypt.md
@@ -0,0 +1,39 @@
+---
+description: Modern alternatives to the bcrypt package for password hashing
+---
+
+# Replacements for `bcrypt`
+
+The native `bcrypt` package is a Node addon. Depending on your constraints, you may prefer a pure JavaScript implementation, or move to built-in cryptographic primitives.
+
+## `bcryptjs`
+
+[`bcryptjs`](https://github.com/dcodeIO/bcrypt.js) is a widely used pure JavaScript implementation with a very similar API surface to `bcrypt`.
+
+```ts
+import bcrypt from 'bcrypt' // [!code --]
+import bcrypt from 'bcryptjs' // [!code ++]
+
+const salt = await bcrypt.genSalt(10) // [!code --]
+const salt = await bcrypt.genSalt(10) // [!code ++]
+
+const hash = await bcrypt.hash('password', salt) // [!code --]
+const hash = await bcrypt.hash('password', salt) // [!code ++]
+```
+
+## `node:crypto` (native, Node.js built-in)
+
+Node provides [`node:crypto`](https://nodejs.org/api/crypto.html) for secure password hashing primitives (for example `scrypt` and `pbkdf2`). This is not a drop-in `bcrypt` API replacement, but it is a common “remove `bcrypt`” direction when you can standardize on a different KDF.
+
+## Web Crypto API (native)
+
+The [Web Crypto API](https://developer.mozilla.org/docs/Web/API/Web_Crypto_API) provides native functionality for cryptographic operations in both web browsers and Node.
+
+> [!NOTE]
+> A few legacy algorithms are intentionally omitted for security reasons (e.g. MD5).
+
+## Bun (built-in)
+
+Bun supports the Web Crypto API natively, and also provides support for streaming hashing via [`Bun.CryptoHasher`](https://bun.sh/docs/api/hashing).
+
+As with the Web Crypto API, many legacy algorithms are intentionally omitted for security reasons (e.g. MD5).
diff --git a/manifests/preferred.json b/manifests/preferred.json
index e275345..a013675 100644
--- a/manifests/preferred.json
+++ b/manifests/preferred.json
@@ -48,6 +48,12 @@
       "replacements": ["fetch", "ofetch", "ky"],
       "url": {"type": "e18e", "id": "fetch"}
     },
+    "bcrypt": {
+      "type": "module",
+      "moduleName": "bcrypt",
+      "replacements": ["bcryptjs", "node:crypto", "crypto", "Bun.CryptoHasher"],
+      "url": {"type": "e18e", "id": "bcrypt"}
+    },
     "bluebird": {
       "type": "module",
       "moduleName": "bluebird",
@@ -2905,6 +2911,11 @@
       "type": "documented",
       "replacementModule": "ansis"
     },
+    "bcryptjs": {
+      "id": "bcryptjs",
+      "type": "documented",
+      "replacementModule": "bcryptjs"
+    },
     "betterknown": {
       "id": "betterknown",
       "type": "documented",

From 1d3059db083965611b9a7bfdd16308b7bc53b92a Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Wed, 29 Apr 2026 09:22:59 +0100
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Roman <dev@rman.dev>
Co-authored-by: James Garbutt <43081j@users.noreply.github.com>
---
 docs/modules/bcrypt.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/modules/bcrypt.md b/docs/modules/bcrypt.md
index 3d0145b..6419cbb 100644
--- a/docs/modules/bcrypt.md
+++ b/docs/modules/bcrypt.md
@@ -4,7 +4,7 @@ description: Modern alternatives to the bcrypt package for password hashing
 
 # Replacements for `bcrypt`
 
-The native `bcrypt` package is a Node addon. Depending on your constraints, you may prefer a pure JavaScript implementation, or move to built-in cryptographic primitives.
+The `bcrypt` package can be replaced by native functionality in most runtimes, or more performant packages.
 
 ## `bcryptjs`
 
@@ -14,16 +14,14 @@ The native `bcrypt` package is a Node addon. Depending on your constraints, you
 import bcrypt from 'bcrypt' // [!code --]
 import bcrypt from 'bcryptjs' // [!code ++]
 
-const salt = await bcrypt.genSalt(10) // [!code --]
-const salt = await bcrypt.genSalt(10) // [!code ++]
+const salt = await bcrypt.genSalt(10)
 
-const hash = await bcrypt.hash('password', salt) // [!code --]
-const hash = await bcrypt.hash('password', salt) // [!code ++]
+const hash = await bcrypt.hash('password', salt)
 ```
 
 ## `node:crypto` (native, Node.js built-in)
 
-Node provides [`node:crypto`](https://nodejs.org/api/crypto.html) for secure password hashing primitives (for example `scrypt` and `pbkdf2`). This is not a drop-in `bcrypt` API replacement, but it is a common “remove `bcrypt`” direction when you can standardize on a different KDF.
+Node provides [`node:crypto`](https://nodejs.org/api/crypto.html) for secure password hashing primitives (for example `scrypt` and `pbkdf2`). This is not a drop-in `bcrypt` API replacement, but is a good option if you can switch to a more secure cryptographic algorithm it supports.
 
 ## Web Crypto API (native)