@@ -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
117126Note that in either case, it is important that you also remove all calls to the old Buffer
118127API manually — just throwing in ` safe-buffer ` doesn't fix the problem by itself, it just provides
0 commit comments