API - Loaders

[bebraw]

Stub.

Feel free to comment here if you have ideas on what this guide should cover. Link to potential resources too.

Reference: https://webpack.github.io/docs/loaders.html

[scarlac]

Assumption: We'll want to keep "Getting started" simple and targeted (mostly) for newbies. If that assumption is wrong, these suggestions will not be relevant.

Avoid mixing of syntax
Webpack syntax is generally complex, more than necessary. In general I would recommend newbies are recommended a (one) normal syntax and the advanced syntax would be hidden away for a dedicated section or advanced topic. This goes for all sections but here's my take on the loaders.

Exclamation syntax - avoid mixing
The loader syntax is one of the bits that can cause a bit of confusion. Perhaps using the array "syntax" is better for the intro docs (ie. preferring loaders: ['style-loader', 'css-loader'] rather than loaders: 'style-loader!css-loader'). Avoid examples of alternative syntax as it is not necessary for getting started with webpack. It's more a matter of choice (thus left to be tweaked later on).

css-loader vs. css - avoid mixing
Again the syntax is not clear. Two options are given and in order to understand how they work, the docs current say:

The loader name convention and precedence search order is defined by resolveLoader.moduleTemplates within the webpack configuration API.

Referring to "precedence search order" and other config options and API, just to understand the difference between loader name syntax in a "getting started" guide should be avoided. Keep it simple at all costs - we should stick to 1 syntax convention and keep the advanced ones hidden away from a Getting Started section.
If newcomers are meant to install 'css-loader' from NPM, it makes sense for them to specify 'css-loader' as the loader name, not 'css' ('css', 'raw', 'style' and other short names makes it seem they are bundled features of Webpack when they are really not special at all)

Consider skipping documenting the CLI. I think most devs are using webpack.config.js and a Getting started guide should reflect that. Using the CLI is a bit more advanced.

Consider using Babel as an example. A lot of devs are using Babel to the point where it would be really helpful for many to get started using Babel.

[bebraw]

Webpack syntax is generally complex, more than necessary. In general I would recommend newbies are recommended a (one) normal syntax and the advanced syntax would be hidden away for a dedicated section or advanced topic. This goes for all sections but here's my take on the loaders.

👍 It's good if we can be opinionated. We can even go as far as to deprecate some ways of doing things in the future (say loader) and recommend good ways here. Currently the API is even too flexible in some ways and that tends to lead to confusion fast.

The loader syntax is one of the bits that can cause a bit of confusion. Perhaps using the array "syntax" is better for the intro docs (ie. preferring loaders: ['style-loader', 'css-loader'] rather than loaders: 'style-loader!css-loader'). Avoid examples of alternative syntax as it is not necessary for getting started with webpack. It's more a matter of choice (thus left to be tweaked later on).

Yup. I've defaulted to loaders on my own material. The only expection is ExtractTextPlugin that forces you to use loader for extraction. Ideally we could write something like loaders: ['style', 'extract', 'css'] for the same effect but I don't think that's going to happen anytime soon. So most likely we have to treat this case as an exception.

It's better to go with verbose syntax by default. If I remember right, webpack 2 provides a nicer variant for query so we could default to that.

If newcomers are meant to install 'css-loader' from NPM, it makes sense for them to specify 'css-loader' as the loader name, not 'css' ('css', 'raw', 'style' and other short names makes it seem they are bundled features of Webpack when they are really not special at all)

Yeah, going with full names could be a good idea. The main problem with abbreviations is that the tooling doesn't really warn you if you write something like css and don't have css-loader installed. webpack-validator might be able to catch this case in the future, though.

So as an alternative we could implement the functionality to webpack-validator and suggest using it. That would take some pain away. But going with full names would be valid too. Even then validation would be useful.

Consider skipping documenting the CLI. I think most devs are using webpack.config.js and a Getting started guide should reflect that. Using the CLI is a bit more advanced.

I've seen an amazing amount of problems around the CLI. Its API doesn't match configuration 100% (esp. webpack-dev-server is painful) and often you end up with hard to debug issues. It's easy to end up using UglifyJsPlugin twice for example if you aren't careful. In the end I've had to check the source to see what exactly the available flags are doing. That's not a good way of doing things.

I might go as far as to deprecate most of the CLI and suggest other methods but that might be just me. From my pov it would be better to push CLI outside of webpack core and let the community come with stronger solutions. If webpack core provided a strong schema, you could generate something on top of that and so on. I would take a strong schema over a CLI any day.

Consider using Babel as an example. A lot of devs are using Babel to the point where it would be really helpful for many to get started using Babel.

Yeah, that could be fitting for a starter tutorial as it's a common problem. I'll be adding a Babel chapter to my webpack book in any case as I want to dig a bit deeper there.

[MarkPieszak]

@bebraw @TheLarkInn I can start taking a stab at this one if you guys would like!
I see it's not assigned to anyone yet.

I was thinking about making a simple combination of both the 1.* loader docs (https://webpack.github.io/docs/loaders.html & https://webpack.github.io/docs/using-loaders.html pages together) along with comments above. Overall, just trying to make it as readable & simple as possible.

Let me know!

[bebraw]

@MarkPieszak Sure! Go ahead. 👍

[TheLarkInn]

@MarkPieszak no pressure just following up since we are about everyone assigned to issues and in progress on them. If you need help feel free to reach out.

[MarkPieszak]

Great! Yeah I'll get moving on this one sorry have been crazy sick the past 2 days 😓
I'll talk to you on slack about where I'm at, once I have a few things together, just to make sure I'm going in the right direction! @TheLarkInn

[TheLarkInn]

Like i said it is no pressure and just reach out and I can give you some guidance.