Config - Elaborate on Source Map Options

[octref]

While browsing webpack's devtool section, I found this stub:

This section is pretty much just copied over from existing docs... imo more background is needed on the different types of source mapping, maybe via links to external sites that discuss the different types of source maps in more detail.

I agree 100%. For general users, most of them only know sourcemap is a mapping between transpiled and un-transpiled code, and allows them to debug in un-transpiled code.

I come to this section with one question:

Which one should I use?

Which boils down to:

• Which one work with Chrome/FF debugger?
• What's the major difference between each one?

However, I walked away with both questions unanswered, while having more questions:

 devtool                      | build | rebuild | production | quality
------------------------------|-------|---------|------------|--------------------------
 eval                         | +++   | +++     | no         | generated code
 cheap-eval-source-map        | +     | ++      | no         | transformed code (lines only)
 cheap-source-map             | +     | o       | yes        | transformed code (lines only)
 cheap-module-eval-source-map | o     | ++      | no         | original source (lines only)
 cheap-module-source-map      | o     | -       | yes        | original source (lines only)
 eval-source-map              | --    | +       | no         | original source
 source-map                   | --    | --      | yes        | original source

• What's the difference between generated/transformed?
• What's "lines only", and how does it affect me?
• What's your definition of quality? And how does the options differ in that aspect?
• What it means for yes/no in "production"? If I were to put webpack in production, I surely want to know what each option does technically.
• What's "cheap"?

Also, I was seeing people using webpack.SourceMapDevToolPlugin() in webpack 2.0. How does that relate to this setting? Which one should I use?

I hope webpack team can keep these questions in mind while reworking on the doc.

[SpaceK33z]

Note that there are a some open questions about source maps for us also, which is why it's hard to write these docs. With webpack/webpack#3165 we hope to get more insights.

[panozzaj]

Thanks for writing up your thoughts on the documentation for devtool, I had similar thoughts while reading through it. My question (original) was more along the lines of speed and understanding the notation of the table. Restated here:

What is the current behavior?

Currently the documentation for devtool configuration is unclear to me, at least for the speed section. It seems like plusses mean that it runs faster. But maybe it means it takes more time? What does o mean? What does - mean?

What is the expected behavior?

It seems like one or more of the following would help:

• a legend describing what the speed symbols mean
• using different symbols (maybe "N/A" or "not applicable" if it is not applicable to that feature)

Crazy idea:

• using a static gauge image of some sort to show the relative speeds for each section

---

Thanks, and hope this helps make the documentation better or give some ideas on where I got confused.

[ecarlisle]

@bebraw : I've been working with source maps quite a bit lately so I'd happy to try a documentation update on this. I do UX design and think @panozzaj 's idea of comparison via data visualization could be a big plus. Sometimes this is as easy as a change in iconography (instead of + or minus). Other times it's reconsidering if something is better expressed as text or via a visualization.

I'd be happy to contribute on this. If that's agreeable, how would you like to track? e.g. PR from a fork or direct assignment? I'm new to this project so I'm not familiar with the workflow yet.

[bebraw]

@ecarlisle Awesome to hear. Please PR. Easier to discuss there. 👍

[skipjack]

Maybe, along with some of the other things discussed, we can link to bits of @simon04's example from webpack/webpack#4698? Would be great to get a solid solution in place for source-mapping docs as it seems there are a lot of open tickets here that relate to it in one way or another.

[skipjack]

@ecarlisle are you still interested in submitting a PR?

I'd be happy to contribute on this. If that's agreeable, how would you like to track? e.g. PR from a fork or direct assignment? I'm new to this project so I'm not familiar with the workflow yet.

A PR from a fork would be great to start. However, if we see that you're contributing often, we may add you as a contributor so you can clone and push branches on the main repo. Re workflow, it's pretty straightforward, just use npm start to start the development server. You can look at the other scripts we have but that's all you should need. Once you submit the initial PR we'll be able to see if any part of the build/testing process fails.

[ecarlisle]

I'm sorry, I fell off the planet for a bit. I'm back now and happy to follow-up. Should we re-open this issue or add new? Thanks!

[skipjack]

@ecarlisle no worries. It's still open btw so let's just continue here. If you would be willing to dig into this that'd be great. I have #1303 open now that fixes some other minor issues with the devtool doc but you should see @sokra's comments there as they add some helpful explanation (as well as a few more options).

In doing that PR, I'm starting to think that maybe there's a slightly better way to lay out the documentation (and maybe even in how to configure the option itself). For example, cheap and module both mean certain things when included in any option (see @sokra's comments on #1303) so maybe defining them separately from the table would make sense (e.g. "Every option can have these variations..." or something).

To go along with that, while I know it would be a breaking change, maybe defining devtool slightly differently would make sense:

module.exports = {
  devtool: {
    cheap: true,
    module: false,
    type: 'eval'
  },
  // ...
}

Anyway, I think a little more discussion and some planning may go a long way.