Discourage mixing CJS and ES6 module syntax in docs

[wyuenho]

Moved from webpack/webpack#3571

Experience has shown that it is easy to fall into a trap like this:

// a.js
import 'whatever';
module.exports = function foo () {};

// b.js
import a from './a.js'; // error, no default member found in a
a.foo();

Much code has been written like this and it used to work in Webpack 2 beta, which only exacerbates the problem of spec-incompliant code like above. Webpack's doc seems to advertise the ability to mix and match different module syntax without mentioning gotchas. I suggest that Webpack should actively discourage this practice when possible, and point people to tools such as eslint-plugin-import to help fix their code.

[wyuenho]

@Kovensky You are absolutely correct. As it happened, when migrating from Node style ES5 code to ES6, we did have a lot of mixed import/module.exports in a bunch of files. I think the gotchas warrant some documentation.

[wyuenho]

Or if Webpack 2 RC implements this behavior, pointing to it might be helpful.

[skipjack]

Sorry for the delay on this, but I completely agree and recently ported the Module Methods and Module Variables documentation from the old doc site in #1209. I think Module Methods would be a good place this warning, something like:

W> While webpack supports multiple module syntaxes, we recommend following a single syntax for consistency and to avoid odd behaviors/bugs. Here's [one example](https://github.com/webpack/webpack.js.org/issues/552) of mixing ES6 and CommonJS, however there are surely others.

at the top of the page under the lead-in paragraph should resolve this. Maybe a small note or link to Module Methods (or both) from the modules concepts page would help as well.

Let me know your thoughts and if you'd be interested in submitting a PR with this change.

[ugultopu]

@skipjack Nice warning. However, even the official getting started guide of webpack is mixing ES6 and CommonJS.

The getting started guide uses Lodash. I've checked out the source code of Lodash and as of version 4.17.4, it uses CommonJS exports.

However, the getting started guide is importing it using the ES6 module syntax. Personally, reading the getting started guide, I cannot wrap my head around how webpack manages to mix different module systems.

The guide is not using Babel, hence we know that ES6 code is not being transpiled to ES5. However, maybe webpack itself is transpiling the ES6 import statements to CommonJS import statements, before transpiling them to a state that is runnable on browser. This is not clear in the guide at all.

[skipjack]

You're misinterpreting the warning. It's not referring to external libraries that your project consumes. It's referring to the local /src code within a project. As @wyuenho pointed out, webpack advertises the fact the it multiple module syntaxes are supported.

This makes it easy to still consume and utilize dependencies that don't necessarily make themselves available through the UMD paradigm. I get that it can be a bit confusing but the fact that webpack supports multiple module definitions is definitely documented.

If you think the warning could be clarified, please feel free to submit a pull request.

[ugultopu]

@skipjack But how does webpack provide interoperability between different module systems? For example, what goes on behind the scenes when I import Lodash using ES6 module syntax? As we know, Lodash is a Node.js module written in CommonJS syntax. How does webpack provide interoperability between these two different module systems?

Is this documented anywhere? If yes, could you point me to the URL of the relevant part of the documentation?

[skipjack]

Webpack essentially converts all these different syntaxes to a "webpack module definition" that provides interoperability and browser compatibility. For more details you'd have to read through the source code, though if you tweet @TheLarkInn he may be able to point you in the right direction.

[ugultopu]

Hi @TheLarkInn,

Sorry for interrupting but I can't wrap my mind around something. Let's say we are importing Lodash, which is an NPM package that uses CommonJS module syntax. We import Lodash using ES6 module syntax.

How does webpack handle the interoperability between these different module systems (CommonJS and ES6 modules)? What goes on behind the scenes?

Is there a section of the documentation that covers this? If yes, could you point me towards the relevant part of the documentation? If not, could you point me towards the relevant parts of the source code of webpack?

Thank you very much

[TheLarkInn]

Ah Sorry for not noticing these (catching up with email debt). The best way to see how the interop works is looking at the webpack runtime code. But it's hard for me to specifically describe the interop in words.

[wyuenho]

Reading webpack’s code also pretty hard LOL

…

On 2 Nov 2017, at 9:07 pm, Sean Larkin ***@***.***> wrote: Ah Sorry for not noticing these (catching up with email debt). The best way to see how the interop works is looking at the webpack runtime code. But it's hard for me to specifically describe the interop in words. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[ugultopu]

@TheLarkInn Are there any particular files that you can recommend reading in the runtime's source code?

[TheLarkInn]

There are a few! However, it is a little broken up across multiple files. I think the best way is to create a bundle and read that generated code. Or see the "/examples" folder in webpack/webpack GitHub repo.