API - Use Real Examples in Loader Documentation

[benwiley4000]

The loaders API page is pretty good.

The code examples are nice. What would be even nicer is if the code examples weren't all so abstract. We know these features exist to be used in real loaders which are used out in the wild, so let's show some of those API usages using source (actual or simplified) of real webpack loaders!

I'm opening this issue since I'm currently trying to figure out how to write my own loader, so unfortunately I don't have great implementation ideas yet. 😢

E.g. This pitch thing sounds useful... but maybe I could see the way some loader I'm already using takes advantage of it?

[benwiley4000]

Another nice thing to have a real-world code example for - async loading using this.async() (including what this looks like from the user perspective when it comes to requiring modules).

[skipjack]

The code examples are nice. What would be even nicer is if the code examples weren't all so abstract. We know these features exist to be used in real loaders which are used out in the wild, so let's show some of those API usages using source (actual or simplified) of real webpack loaders!

Hmmm, that guide is already pretty detailed and looks like it has at least a simple example for each section. Maybe we could link to some well written loaders that take advantage of various api features for people to dig through the source as an example? I just worry about the guide getting too bloated...

Did you have any loaders in mind that you think are well written and would make good examples?

[skipjack]

Closing for inactivity... @benwiley4000 if you still have ideas of good loaders for reference when learning I would submit a PR to add a related section to the YAML front-matter of the Loaders API page.

E.g. This pitch thing sounds useful... but maybe I could see the way some loader I'm already using takes advantage of it?

There is another discussion at #449 if you're interested in discussing or contributing to the pitch docs.

[benwiley4000]

Ok, sorry for not responding before.

One example is this notion of a loader passing multiple results, casually brought up in the async loaders section. My eyes sort of started glazing over when I read that because there is absolutely no reference to any specific pair of loaders which would make use of this kind of hand-off. It sounds like maybe what I want, but I'm so confused trying to understand how it's used or why.

P.S. I reread some docs pages and it seems like the third argument is always the source map but I'm not sure what ast is in that example.

P.P.S. Ok I found that answer by looking at the section on the callback arguments. It seems like all this information is here.. but I'm not sure why I've had such a frustrating time trying to find it. 😞 I don't usually have this kind of trouble with documentation.

Compounding my confusion was probably that "multiple results" sounds like I'm loading an array of assets, or something like that.

[skipjack]

One example is this notion of a loader passing multiple results, casually brought up in the async loaders section. My eyes sort of started glazing over when I read that because there is absolutely no reference to any specific pair of loaders which would make use of this kind of hand-off. It sounds like maybe what I want, but I'm so confused trying to understand how it's used or why.

Have you come across a good example we could link to? @bebraw do you know of any?

P.S. I reread some docs pages and it seems like the third argument is always the source map but I'm not sure what ast is in that example.

P.P.S. Ok I found that answer by looking at the section on the callback arguments. It seems like all this information is here.. but I'm not sure why I've had such a frustrating time trying to find it. 😞 I don't usually have this kind of trouble with documentation.

Compounding my confusion was probably that "multiple results" sounds like I'm loading an array of assets, or something like that.

I'm glad you were able to figure out what you needed to and yes I know much of our documentation isn't perfectly structured or well-reviewed yet. We get a lot of open source contributions, which is 🎉 , but we're still in the process of building a solid group of reviewers and content writers that continually contribute. The good news is that now that we've worked our way through much of the backlog of missing documentation, we are now starting to review and clean up the content that's there (e.g. #1258 and all the recent guides related prs). We'll start to review the other sections besides guides soon as well.

Now that you do understand the documentation there though, maybe you have some ideas for how it could be cleaned up or structured better? We'd be glad to accept a PR if you do have ideas.

[benwiley4000]

I'll think on it, and might contribute some if I come across any breakthroughs. For the moment I've decided a loader was too complicated to write/beyond the scope of the problem I needed to solve, but it's still on my radar for sure. Thank you for being patient with me! 😄

It's not that a loader or plugin couldn't be useful, but it seems like too much development effort just to make an existing tool that works conform to webpack's build style - especially now that I think I would need a plugin, not a loader. I want to take a GIF as a resource and keep that GIF while also spitting out one or more frames as jpegs (or whatever - the user should be able to pipe the data for each frame into a loader, and get an array of all those results at the end). I've considered the ExtractTextPlugin as a model to follow, but mine is a very specific use case, for displaying a still frame preview while a GIF is loading. The goal was to make setup simple for users of my GIF display library, but if it requires much unintuitive configuration (as ExtractTextPlugin does) then I'm not sure I'll be doing them a favor. 😞

But... if you know any magic API solutions for the kind of problem I'm trying to solve here, I'd love to hear them. I've just gotten pretty lost trying to think through it all with webpack goggles on.

[bebraw]

Have you come across a good example we could link to? @bebraw do you know of any?

Technically you can pack/unpack from/to object structures as long as you get something webpack understands (currently just JS module) out of the chain. You can also emit files from loaders easily (file-loader).