From d37756a973d48c4e924344916823a9189cbfa454 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Wed, 20 Dec 2023 03:17:04 -0500
Subject: [PATCH] [doc] Clarify legacy deps (#2184)

---
 README.md | 52 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 31 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index a550ca1c7..82aa26a48 100644
--- a/README.md
+++ b/README.md
@@ -57,27 +57,37 @@ npm install ws
 
 ### Opt-in for performance
 
-There are 2 optional modules that can be installed along side with the ws
-module. These modules are binary addons that improve the performance of certain
-operations. Prebuilt binaries are available for the most popular platforms so
-you don't necessarily need to have a C++ compiler installed on your machine.
-
-- `npm install --save-optional bufferutil`: Allows to efficiently perform
-  operations such as masking and unmasking the data payload of the WebSocket
-  frames.
-- `npm install --save-optional utf-8-validate`: Allows to efficiently check if a
-  message contains valid UTF-8.
-
-To not even try to require and use these modules, use the
-[`WS_NO_BUFFER_UTIL`](./doc/ws.md#ws_no_buffer_util) and
-[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment
-variables. These might be useful to enhance security in systems where a user can
-put a package in the package search path of an application of another user, due
-to how the Node.js resolver algorithm works.
-
-The `utf-8-validate` module is not needed and is not required, even if it is
-already installed, regardless of the value of the `WS_NO_UTF_8_VALIDATE`
-environment variable, if [`buffer.isUtf8()`][] is available.
+`bufferutil` is an optional module that can be installed alongside the `ws`
+module:
+
+```
+npm install --save-optional bufferutil
+```
+
+This is a binary addon that improves the performance of certain operations such
+as masking and unmasking the data payload of the WebSocket frames. Prebuilt
+binaries are available for the most popular platforms, so you don't necessarily
+need to have a C++ compiler installed on your machine.
+
+To force `ws` to not use `bufferutil`, use the
+[`WS_NO_BUFFER_UTIL`](./doc/ws.md#ws_no_buffer_util) environment variable. This
+can be useful to enhance security in systems where a user can put a package in
+the package search path of an application of another user, due to how the
+Node.js resolver algorithm works.
+
+#### Legacy opt-in for performance
+
+If you are running on an old version of Node.js (prior to v18.14.0), `ws` also
+supports the `utf-8-validate` module:
+
+```
+npm install --save-optional utf-8-validate
+```
+
+This contains a binary polyfill for [`buffer.isUtf8()`][].
+
+To force `ws` to not use `utf-8-validate`, use the
+[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment variable.
 
 ## API docs