webpack-contrib
Documentation: Missing important information
Documentation is:
- [X] Missing
- [X] Needed
- [ ] Confusing
- [ ] Not Sure?
Please Explain in Detail...
From my perspective, the documentation is missing crucial information.
First of all, it isn't clear that this loader is about. It "exports HTML as string". Where is that string stored? Where are we in the processing pipeline when html-loader finishes? What if html-loader is the only loader ran for *.html?
The sources section doesn't explain the sources.list.type and sources.list.filter attributes.
In the sources section it reads:
By default every loadable attribute (for example -
<img src="image.png">) is imported (const img = require('./image.png') ornew URL("./image.png", import.meta.url)).
… in HTML?? What is the result? And example of the resulting conversion content is missing.
In the esModule section it reads:
By default,
html-loadergenerates JS modules that use the ES modules syntax. If you want to generate CommonJS modules instead (e.g.,module.exports =), set:
… again, in HTML?? What is the result? And example of the resulting conversion content is missing.
"Export into HTML files" is suggesting an interesting option for transforming HTML source, but then loses track by …
- mentioning non-existing "extract loader"s
- the example introduces two distinct
testrules, while not explaining why.
Your Proposal for Changes
Please comb through the documentation and fix the above mentioned issues.
First of all, it isn't clear that this loader is about. It "exports HTML as string". Where is that string stored? Where are we in the processing pipeline when html-loader finishes? What if html-loader is the only loader ran for *.html?
In file where you "import" HTML file, mostly it is JS file, but you can import HTML file everywhere (some exotic cases and setup), even HTML in HTML
again, in HTML?? What is the result? And example of the resulting conversion content is missing.
We store string in JS file, in context of JS and Node.js we have commonjs format and ES modules, not sure what we should improve here
Other things can be improved
Thanks for clarifying, @alexander-akait!
Regarding to esModule: The loader pipeline results are opaque. So, what does the resulting JS file look like for a simple html input, like, e.g., <html></html>? Why is the esModule switch relevant for HTML?
If I wanted to write a loader that's importing HTML fragments from other files into HTML, what would I expect to get from html-loader?
Regarding to esModule: The loader pipeline results are opaque. So, what does the resulting JS file look like for a simple html input, like, e.g., ? Why is the esModule switch relevant for HTML?
With esModule: true we generate export default "<YOU_HTML>", with false - module.exports = "<YOUR_HTML>", in most of cases you don't need this option, that is why it is true by default, but for some legacy system developers want to generate commonjs code, it is more about legacy
If I wanted to write a loader that's importing HTML fragments from other files into HTML, what would I expect to get from html-loader?
html-loader generate JS code, so you need execute it if you want to return string, but if you want to work with generated content like with JS (i.e. adding extra runtime logic) you need to use pitch loader - https://webpack.js.org/api/loaders/#pitching-loader