Feedback on the front page UX for getting started with Webpack

[lgarron]

I've interacted with webpack in the past and have generally had painful experiences. A conversation with someone encouraged me to look at webpack again to see if things have improved. I'm happy to say that compatibility with my published packages is now a lot smoother, but I took notes on my experience and ran into a lot of small stumbles.

These notes stem from visiting https://webpack.js.org/ and going from there.

---

1. https://webpack.js.org/ states "Without config or provide custom webpack.config.js". Why is the first instruction to go somewhere else to watch a video? The video is almost 8 hours, how much of it should I watch? Am I missing something if I don't watch the video?
2. It states "Then run webpack on the command-line to create bundle.js." No mention of installation or setup, but webpack sure isn't in my $PATH to start. 🤷
3. The sample config 1) is CommonJS, 2) imports 'path' instead of 'node:path', and 3) uses __dirname. Not an issue per se, but heuristically a red flag that a project is stuck with outdated workarounds instead of modern standards. (And also an actual red flag in my editor because the 'path' import is marked as a lint error.)
4. The website said to run webpack, so I tried npx webpack. This gave me a prompt about installing webpack-cli, which I accepted. It then failed with error: Cannot find module 'webpack-cli/package.json'. Running npx webpack a second time works (so something is definitely not idempotent) but outputs as well as red text that the 'mode' option has not been set even though I'm using a sample config from the front page of webpack!
5. npx webpack just builds dist/bundle.js. I can serve the dir myself, but presumably there's a dev server? I'm not sure how much I agree with the "Awesome, isn't it?" on the front page at this point.

Tried installing cubing and adding import { randomScrambleForEvent } from "cubing/scramble"; randomScrambleForEvent("333").then((scramble) => scramble.log()); to the JS. That works!

However:

6. import.meta.resolve(…) resolution is not implemented and results in a red herring warning of "Critical dependency: Accessing import.meta directly is unsupported (only property access or destructuring is supported)".

Also tried installing cubing, importing "cubing/twisty" (in JS) and adding <twisty-player alg="R U R'"></twisty-player> to page.html. Seems to work!

7. Tried replacing the <script …> tag in page.html with <script src="cubing/twisty"></script>. Doesn't load the appropriate JS. 🤷 (This is understandable, but it means module resolution semantics are contextual.)
8. The front-and-center splash animation on the page brags about being able to bundle styles, with module dependencies between JS and SASS. However, https://webpack.js.org/loaders/css-loader/ and https://webpack.js.org/loaders/sass-loader/ state that they each are "a third-party package maintained by community members, it potentially does not have the same support, security policy or license as webpack, and it is not maintained by webpack." So I guess your flagship functionality is not officially supported???? An ecosystem relying on community contributions is a fine technical decision, but I would be very worried avout where to report issues and avoid them slipping through cracks. (By contrast, it's very clear where to report issues for "batteries included" bundlers.)
9. https://webpack.js.org/loaders/css-loader/ says to write import * as css from "file.css"; without any further context. If I didn't know about Webpack before, I would assume that this is invalid code. There's no explanation of why I should be able to load CSS from JS or what value css will have in the code below the import. I tried logging css and it's a JS module rather than a CSSStyleSheet. Any reason this line shouldn't just be import "file.css";?
10. Very nitpicky, but the webpack.config.js example at https://webpack.js.org/loaders/css-loader/ implies that the entire config should be replaced with just configuration for the module field. The front page includes ... on some in some places indicate that there would be more code inbetween lines of sample code. A line or two of // ... would be very appropriate here.
11. https://webpack.js.org/loaders/css-loader/ tells you to install a separate package css-loader and add it to the config manually. Sure. But then the example also includes use: ["style-loader", "css-loader"]. So do I also need to install style-loader? https://webpack.js.org/loaders/style-loader/ mentions "It's recommended to combine style-loader with the css-loader" but that doesn't explain anything. I'll try following the example to the letter for now.
12. Also very nitpicky, but: the example mentions file.css but doesn't actually show/say to create the file. But okay, unless you're an absolute beginner to web programming you can probably infer that. (I made one and placed html { background: coral; } in it.) However, this is inconsistent with the full set of files in the front page example.
13. Compiling the example results in an error. I actually anticipated this issue as I was pasting the example, but I appreciate that the error message makes it easy for beginners to tell what the fix is:

Module not found: Error: Can't resolve 'file.css' in '/Users/lgarron/Downloads/fdslkjf/src'
Did you mean './file.css'?

That said, this seems to be another example of inconsistent module resolution semantics.

14. At this point, npx webpack is already taking more than 5 seconds to run. I'm used to being able to bundle a JS project with 360 files in 50ms. Either this is a huge red flag for performance, or I'm missing an important tip. There is also no output of any kind until the command is done, which means it's unclear at first if anything is happening.
15. Now the main error is:

Module not found: Error: Can't resolve 'style-loader' in '/Users/lgarron/Downloads/fdslkjf'
resolve 'style-loader' in '/Users/lgarron/Downloads/fdslkjf'
  Parsed request is a module
  using description file: /Users/lgarron/Downloads/fdslkjf/package.json (relative path: .)
    resolve as module
      looking for modules in /Users/lgarron/Downloads/fdslkjf/node_modules
        single file module
          using description file: /Users/lgarron/Downloads/fdslkjf/package.json (relative path: ./node_modules/style-loader)
            no extension
              /Users/lgarron/Downloads/fdslkjf/node_modules/style-loader doesn't exist
            .js
              /Users/lgarron/Downloads/fdslkjf/node_modules/style-loader.js doesn't exist
        /Users/lgarron/Downloads/fdslkjf/node_modules/style-loader doesn't exist
      /Users/lgarron/Downloads/node_modules doesn't exist or is not a directory
      /Users/lgarron/node_modules doesn't exist or is not a directory
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory

I can understand what's happening here, but the the actual error easily scrolls of the screen and the tail of the output (i.e. the part that stays on screen) is not really useful.

Installed style-loader. The CSS import is now reflected on the page! 🥳

16. It seems I can specify both a JS and a CSS file in "entry" in the config. Yay! But it seems they are still bundled into a single JS file? How do I compile my CSS separately in order to avoid a CSS-in-JS performance hit?

I'm able to install @cubing/[email protected] and @import "@cubing/icons/css"; from CSS successfully. Even the font is bundled. Glad to see it. 🤩

---

I haven't really polished these notes, so I apologize that they are a bit blunt. But if you're interested in feedback from an experienced web developer, I hope it provides an unfiltered view of the UX on your front page.

[lgarron]

6. import.meta.resolve(…) resolution is not implemented and results in a red herring warning of "Critical dependency: Accessing import.meta directly is unsupported (only property access or destructuring is supported)".

This seems to be: webpack/webpack#16693

I would be very glad to see this implemented, as it removes the need for a lot of hacks when it comes to web workers and WASM in published packages.