Skip to content

Commit d37756a

Browse files
authoredDec 20, 2023
[doc] Clarify legacy deps (#2184)
1 parent a57e963 commit d37756a

File tree

1 file changed

+31
-21
lines changed

1 file changed

+31
-21
lines changed
 

‎README.md

+31-21
Original file line numberDiff line numberDiff line change
@@ -57,27 +57,37 @@ npm install ws
5757

5858
### Opt-in for performance
5959

60-
There are 2 optional modules that can be installed along side with the ws
61-
module. These modules are binary addons that improve the performance of certain
62-
operations. Prebuilt binaries are available for the most popular platforms so
63-
you don't necessarily need to have a C++ compiler installed on your machine.
64-
65-
- `npm install --save-optional bufferutil`: Allows to efficiently perform
66-
operations such as masking and unmasking the data payload of the WebSocket
67-
frames.
68-
- `npm install --save-optional utf-8-validate`: Allows to efficiently check if a
69-
message contains valid UTF-8.
70-
71-
To not even try to require and use these modules, use the
72-
[`WS_NO_BUFFER_UTIL`](./doc/ws.md#ws_no_buffer_util) and
73-
[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment
74-
variables. These might be useful to enhance security in systems where a user can
75-
put a package in the package search path of an application of another user, due
76-
to how the Node.js resolver algorithm works.
77-
78-
The `utf-8-validate` module is not needed and is not required, even if it is
79-
already installed, regardless of the value of the `WS_NO_UTF_8_VALIDATE`
80-
environment variable, if [`buffer.isUtf8()`][] is available.
60+
`bufferutil` is an optional module that can be installed alongside the `ws`
61+
module:
62+
63+
```
64+
npm install --save-optional bufferutil
65+
```
66+
67+
This is a binary addon that improves the performance of certain operations such
68+
as masking and unmasking the data payload of the WebSocket frames. Prebuilt
69+
binaries are available for the most popular platforms, so you don't necessarily
70+
need to have a C++ compiler installed on your machine.
71+
72+
To force `ws` to not use `bufferutil`, use the
73+
[`WS_NO_BUFFER_UTIL`](./doc/ws.md#ws_no_buffer_util) environment variable. This
74+
can be useful to enhance security in systems where a user can put a package in
75+
the package search path of an application of another user, due to how the
76+
Node.js resolver algorithm works.
77+
78+
#### Legacy opt-in for performance
79+
80+
If you are running on an old version of Node.js (prior to v18.14.0), `ws` also
81+
supports the `utf-8-validate` module:
82+
83+
```
84+
npm install --save-optional utf-8-validate
85+
```
86+
87+
This contains a binary polyfill for [`buffer.isUtf8()`][].
88+
89+
To force `ws` to not use `utf-8-validate`, use the
90+
[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment variable.
8191

8292
## API docs
8393

0 commit comments

Comments
 (0)
Please sign in to comment.