Skip to content

Commit 6aaedb2

Browse files
LinusUTrott
authored andcommitted
Put Buffer polyfills in a list (#1674)
* Put Buffer polyfills in a list Per discussion here: https://github.com/nodejs/nodejs.org/pull/1666/files#r191602869 The idea is to give a more equal view of all the options. Removed the drawback about the number of dependencies of `buffer-from` and `buffer-alloc` since those 4 dependencies are smaller than the 1 `safer-buffer`.
1 parent e3dd7f6 commit 6aaedb2

File tree

1 file changed

+30
-21
lines changed

1 file changed

+30
-21
lines changed

locale/en/docs/guides/buffer-constructor-deprecation.md

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -92,27 +92,36 @@ your users will not observe a runtime deprecation warning when running your code
9292
<a id="variant-2"></a>
9393
## Variant 2: Use a polyfill
9494

95-
Utilize [safer-buffer](https://www.npmjs.com/package/safer-buffer) as a polyfill to support older
96-
Node.js versions.
97-
98-
You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill
99-
`const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API.
100-
101-
Make sure that you do not use old `new Buffer` API — in any files where the line above is added,
102-
using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though.
103-
104-
Alternatively, you could use [buffer-from](https://www.npmjs.com/package/buffer-from) and/or
105-
[buffer-alloc](https://www.npmjs.com/package/buffer-alloc) [ponyfills](https://ponyfill.com/)
106-
those are great, the only downsides being 4 additional dependencies and slightly more code changes to
107-
migrate off them (as you would be using e.g. `Buffer.from` under a different name). If you need only
108-
`Buffer.from` polyfilled — `buffer-from` alone which comes with no extra dependencies.
109-
110-
_Alternatively, you could use [safe-buffer](https://www.npmjs.com/package/safe-buffer) — it also
111-
provides a polyfill, but takes a different approach which has
112-
[its drawbacks](https://github.com/chalker/safer-buffer#why-not-safe-buffer). It will allow you
113-
to also use the older `new Buffer()` API in your code, though — but that's arguably a benefit, as
114-
it is problematic, can cause issues in your code, and will start emitting runtime deprecation
115-
warnings starting with Node.js 10._
95+
There are three different polyfills available:
96+
97+
- **[safer-buffer](https://www.npmjs.com/package/safer-buffer)** is a drop-in replacement for the
98+
entire `Buffer` API, that will _throw_ when using `new Buffer()`.
99+
100+
You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill
101+
`const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API.
102+
103+
Do not use the old `new Buffer` API. In any files where the line above is added,
104+
using old `new Buffer()` API will _throw_.
105+
106+
- **[buffer-from](https://www.npmjs.com/package/buffer-from) and/or
107+
[buffer-alloc](https://www.npmjs.com/package/buffer-alloc)** are
108+
[ponyfills](https://ponyfill.com/) for their respective part of the `Buffer` API. You only need
109+
to add the package(s) corresponding to the API you are using.
110+
111+
You would import the module needed with an appropriate name, e.g.
112+
`const bufferFrom = require('buffer-from')` and then use that instead of the call to
113+
`new Buffer`, e.g. `new Buffer('test')` becomes `bufferFrom('test')`.
114+
115+
A downside with this approach is slightly more code changes to migrate off them (as you would be
116+
using e.g. `Buffer.from` under a different name).
117+
118+
- **[safe-buffer](https://www.npmjs.com/package/safe-buffer)** is also a drop-in replacement for
119+
the entire `Buffer` API, but using `new Buffer()` will still work as before.
120+
121+
A downside to this approach is that it will allow you to also use the older `new Buffer()` API
122+
in your code, which is problematic since it can cause issues in your code, and will start
123+
emitting runtime deprecation warnings starting with Node.js 10
124+
([read more here](https://github.com/chalker/safer-buffer#why-not-safe-buffer)).
116125

117126
Note that in either case, it is important that you also remove all calls to the old Buffer
118127
API manually — just throwing in `safe-buffer` doesn't fix the problem by itself, it just provides

0 commit comments

Comments
 (0)