Webpack.js.org: Shimming: Node Built-Ins

[pksjce]

_From @wearhere on August 14, 2016 22:53_

I'm submitting a feature request

Webpack version:
1.13.1

Please tell us about your environment:
OSX 10.11.5

Current behavior:
Webpack's automatic shimming of Node built-ins is not documented so far as I can tell.

Expected/desired behavior:

• What is the expected behavior?

It would be documented, specifically (my stabs at documentation follow the colons):

• how it's triggered: you require a Node built-in or use a Node global anywhere in
  your input to Webpack
• what modules/globals are shimmed: so far I have seen os, crypto, and Buffer
• how to disable this shimming: define the module as an external
  or use DefinePlugin to wrap the require in a dead branch
  
  
  
  • What is the motivation / use case for changing the behavior?
  
  

I'm actually not advocating changing the automatic shimming, I just think it should be documented. It can be very nice, but is somewhat surprising, and you might accidentally bundle a huge shim using code like:

js var os = require('os'); var crypto; if (os.platform() === 'browser') { crypto = window.crypto; } else { crypto = require('crypto'); }

not realizing that you need to either mark 'crypto' as an external or define-out the latter branch.

Also if the shims used aren't documented, it's not clear where you'd go to file bugs against them (is Webpack responsible for them per se?)

• Browser: all
• Language: all

_Copied from original issue: webpack/webpack#2871_

[pksjce]

_From @wearhere on August 14, 2016 23:35_

Some further niceties:

• It might also be nice for Webpack to log, in its build output, what modules were shimmed, just so the developer can double-check what they expected to happen.
• I think Webpack should suggest that developers use browser APIs where available rather than relying on the shims. For instance, SubtleCrypto is almost equivalent to crypto, the former's use of promises aside. Developers can save 100kB of JS, and worry less about correctness, by using the browser's API vs. a 3rd-party implementation.

[pksjce]

_From @TheLarkInn on August 18, 2016 15:3_

@wearhere you mind posting this issue also on Our new docs repo. This will help us track it in both places.

[bebraw]

Closing in favor of #13.

[bebraw]

Let's re-open. We need to cover the Node bits in greater detail. Missed that on the first pass.

[skipjack]

Ah! I think this was actually tackled recently by @oneforwonder -- see this page. Maybe we should just add a small section to the shimming guide that links there?

[bebraw]

Ah! I think this was actually tackled recently by @oneforwonder -- see this page. Maybe we should just add a small section to the shimming guide that links there?

Yup. Good to close after that.