Webpack.js.org: Guides - Review and Simplify

[TheDutchCoder]

I'm currently following the guides as I'm new to webpack and even though the start (setup and first example) is very clear, the guides quickly become vague and (worse) they don't seem to yield working results.

To give you a concrete example: Code Splitting - CSS:
The first example on this page will result in an error, as no input or output is specified. Nor does it contain any information on how to load the result in a page. This might seem arbitrary to experienced users, but I think it's important.

Another one is: Code Splitting - Async:
The import example will actually result in webpackJSONp errors and create a 0.bundle.js file that can not be resolved when loaded in a page. It's also a very unexpected output (why is this file here and what is it supposed to do?)

I believe this can be incredibly discouraging to beginners as they might want to see "fully working" examples so they can grasp what is going on.

Would it be appreciated if I fork this part of the docs and try to improve them a bit? Not sure how contributions are normally done ;)

Since I'm a beginner myself, I might need some help on it, as I'll probably won't be able to get everything working without good docs 😄

[TheLarkInn]

I wonder if we should be adding html-webpack-plugin as a easy bootstrap to getting people started, even if they don't understand right away. It will handle some of the nuances like putting async and main chunks in the right order on the html, etc.

[TheDutchCoder]

Yeah that might be a good idea. It would certainly help testing out the examples without the frustration of having to figure out how files should be called in a page.

Currently following all guides and proposing some changes (if that's alright) ,so they're consistent and basically build off of the first main example.

[rafaeleyng]

Another one is: Code Splitting - Async:
The import example will actually result in webpackJSONp errors and create a 0.bundle.js file that > can not be resolved when loaded in a page. It's also a very unexpected output (why is this file here > and what is it supposed to do?)

I will give my experience at this: some months ago, even already being a Webpack user for 1 year and having worked with RequireJS, I tried to setup code splitting with Webpack following the guides, and I was unable to get it working.

I'm planning to check it again the next few days, so I can give a more up-to-date feedback then.

[skipjack]

I'm currently following the guides as I'm new to webpack and even though the start (setup and first example) is very clear, the guides quickly become vague and (worse) they don't seem to yield working results.

Yes, these docs are still very much a work in progress. We're still catching up a bit with the backlog but we're slowly starting to clean the existing content up as well. I think many of them can be simplified, re-organized, and some should be significantly reduced in scope. For an example, see #1251 -- it includes more than just guides work but I'd be interested in your thoughts on the simpler HMR guide added there.

Thanks for highlighting those two examples. I also see you opened a pr for code-splitting-libraries which I'll review shortly.

Would it be appreciated if I fork this part of the docs and try to improve them a bit? Not sure how contributions are normally done ;)

That would be awesome! See our Writer's Guide and feel free to ping me if you have any questions re the build process. As it stands this issue is a bit broad right now... it would be great if we could go through them one or two at time so we can discuss, review and revise each one in detail before moving on to the next.

Since I'm a beginner myself, I might need some help on it, as I'll probably won't be able to get everything working without good docs 😄

We're definitely here to help. I think having a beginner test them all is actually a really good test of how solid each guide is. Like I said, let me know if there's anything I can do to facilitate, you can reach me on gitter.

On a separate note, I'll be writing a blog post soon that outlines the status of this repo and current plan for going forward. Hoping to have it up by next week.

[skipjack]

I wonder if we should be adding html-webpack-plugin as a easy bootstrap to getting people started, even if they don't understand right away. It will handle some of the nuances like putting async and main chunks in the right order on the html, etc.

@TheLarkInn I agree and even just moving the "Managing Built Files" guide up in the order of guides (maybe even to right after "Getting Started") would help significantly as well. I found @sokra's comment from the other day really helpful in understanding webpack and how it should be looked at:

webpack is the advanced config, and tools like create-react-app, angular-cli, preact-cli and the simple configs...
webpack is a low level tool

I think webpack should be made as approachable and easy to get started with as possible __without__ compromising it's flexibility and customizability. For some people it might make sense to use those higher-level tools, which use webpack under the hood, at least to start. Maybe adding this to the docs somewhere wouldn't be a bad idea.

However, even with all that said, I think it's actually a lot easier to get started with webpack than most people think. A simple webpack config with just a few loaders can go _a long way_. It's the optimizations and customizations that come into the conversation quite often that I think throw many people off.

[TheDutchCoder]

So going through the new order and doing work on the guides, I need some feedback on what would be a good approach.

I think "Getting Started" is a great entry point (pun intended) and the follow up "Asset Management" makes a lot of sense as well.

But what should be next I find hard to judge as a new user. Maybe something that explains the html-webpack-plugin would be good, so people know how things can be dynamically added to their index.html.

From there maybe on to "Code Splitting", followed by "Output Management" and "Production".

I think that would cover most "Basic Guides", from setting up a very simple project, all the way to a deployable piece of code.

Then "Advanced Guides" would include things like "Development", "Dependency Management", and other topics I don't know about (yet).

So to summarize, I'd propose something like this:

• Introduction
• Installation
• Basic Guides
  
  
  
  • Getting Started
  
  
  • Asset Management
  
  
  • Output Management (includes html-webpack-plugin)
  
  
  • Development (I would like a different name for this, if possible)
  
  
  • Hot Module Reloading
  
  
  • Building for Production
  
  
• Advanced Guides
  
  
  
  • Code Splitting
  
  
  • Lazy Loading
  
  
  • Dependency Management
  
  
  • Tree Shaking
  
  
  • Caching
  
  
  • Shimming
  
  
  • ?
  
  

[skipjack]

__Output Management__ does describe the html-webpack-plugin which is why I put it after __Asset Management__. I don't think extending the __Asset Management__ guide any more is a good idea as it's already getting pretty long with #1305 (reviewing now). I also think __Code Splitting__ (and all it's variations) are more advanced than __Development__ or __Hot Module Replacement__. I think __Development__ and __Building for Production__ are guides everyone will need while __Code Splitting__ is more of an optimization step (although it probably could be bumped a bit higher in the hierarchy).

I'd like to tackle __Code Splitting__, it's variations, and __Lazy Load - React__ as I think there's a significant amount of overlap and I think we can simplify them a bit. There's also a few things in the current list that I think could either be dropped for now or moved elsewhere.

[TheDutchCoder]

Alright sounds good, so we could move Development and HMR under "Basic" and then move Code Splitting and Lazy Loading under Advanced. Let me update the list to reflect that.

[skipjack]

Ok so an update:

• [x] Introduction
• [x] Installation
• [x] Getting Started
• [x] Asset Management
• [x] Output Management (Done: #1344)
• [x] Development (Done: #1405)
• [x] Hot Module Replacement (Done: #1439)
• [x] Production (#1331) (Done: #1508)
• [x] Tree Shaking (#1331) (Done: #1508)
• [x] Code Splitting (Done: #1338)
• [x] Lazy Loading (Done: #1338)
• [x] Caching (#652) (Done: #1436)
• [x] Authoring Libraries (Done: #1532)
• [x] Shimming (#938) (Done -- #1579)
• [x] Typescript (Done: #1530)
• Migrating Versions (_differs from normal guides_)
• Build Performance (_differs from normal guides_)
• Environment Variables (_consider dropping or moving elsewhere_)
• Development - Vagrant (_hmmm_)
• Dependency Management (_hmmm_)
• Public Path (_consider dropping or moving elsewhere_)
• Integrations (_hmmm_)

The last few are ones I'm not sure should even stick around (maybe need to be moved or merged). I'm checking the ones that are already done and putting the lead person's name on any that have been discussed and decided on (or are already in progress). Let's keep updating this list as we go... once we're most of the way through the core guides this issue can be closed 👍 .

[skipjack]

@TheDutchCoder @jakearchibald as mentioned in #1338 please feel free to do another pass over the _Code Splitting_ and _Lazy Loading_ changes now that it's merged.

@jakearchibald are you still interested in tackling the caching guide (which should hopefully resolve #652 and synchronize it with the others)?

@TheDutchCoder as mentioned in #1338, I'll begin reviewing your PRs as soon as I can.

If either of you have your eyes on any re-working any other guides feel free to claim them. I'm happy to pick up whatever .

[skipjack]

@TheDutchCoder I may pick up the _Caching_ guide if we don't hear back from @jakearchibald soon as it's been a high priority with #652 and I think the updates would resolve @rafde's issues from #1366 (specifically highlighting of vendor splitting). I'll review your and @rouzbeh84's open PRs later today.

[jakearchibald]

Go for it, I'm bogged down with other stuff right now.

[skipjack]

Ok I will at least ping you for reviews if that's alright. Your comments on #1338 were very helpful.

[jakearchibald]

Sure, happy to review! Sorry I couldn't have contributed more.

[TheDutchCoder]

Also: we should update our guides examples to use webpack 3, as it will be installed on an npm install in the examples (hope it's okay to link to that)

[mtrivera]

I can work on the Typescript guide

[skipjack]

@TheDutchCoder for sure... note that I did add a warning to the index page noting that the output may not always be exactly the same in #1364.

[skipjack]

@mtrivera that would be great, thanks for jumping over here. Please use the other guides we've finished so far as a baseline -- maybe you can extend off of one of the first ones and show how it needs to be tweaked to allow typescript?

Also, this gives me a good excuse to clearly define the goal for our guides (as discussed in #1380). Here goes, and I'll probably add these short statements to the README or CONTRIBUTING repo pages soon:

Guides

This section is meant to provide simple, framework-agnostic tutorials that progress through the core features of webpack in a logical manner. Many of them stem from previous guides, which will be noted at the top, so it does help to read through them in order.

@TheDutchCoder sound good? Also could you help advise @mtrivera or any others who make their way over? Between #1380, being sick, and traveling I have my hands full at the moment. Going to be working on reviewing prs, starting with yours, today and tomorrow.

[TheDutchCoder]

👍 Sounds great to me! Thanks!

[marioacc]

I can work in the Authoring Libraries section, I would be pleased to. 👍

[sbaidon]

I would like to help on the Hot Module Replacement Guide, if that is being simplified as well

[skipjack]

@marioacc _Authoring Libraries_ is all yours. That one's a great choice because it's somewhat decoupled from the rest.

[skipjack]

@sbaidon I gave you _Hot Module Replacement_ but you may want to wait until @TheDutchCoder finishes _Development_ as HMR is a logical follow up. I think you two can sync up re those guides.

[TheDutchCoder]

👍

Working on that as we speak, I should be able to open a PR for that sooner rather than later. It will still cover pretty much everything in the current guide, just rewritten and with some additions.

So if you want to start, you probably can be reading through the current Development guide to see what's covered.

[sbaidon]

Thanks @skipjack!

@TheDutchCoder, what works best for you to stay in touch?

[TheDutchCoder]

@sbaidon good question, so far I've been communicating through GitHub, but I assume there's a Slack channel we could join?

cc @skipjack ?

[marioacc]

@skipjack perfect! I would start working on it ASAP.

[skipjack]

@sbaidon just merged #1405 so you should be good to stem off that for _Hot Module Replacement_. By the way, I did rewrite that guide recently so it is in pretty good shape but doesn't go into too much detail or stem from _Development_.

@TheDutchCoder @sbaidon yes there is a slack channel that I think we can get you both invited to. However I'm not too familiar with slack and not sure if I have permission to send the invite. @TheLarkInn @bebraw?

Also, some of us use gitter at times as well.

[TheDutchCoder]

Gitter/Discord is fine too for me.
I'm already on the Vue.js gitter channel, so I hopped on the webpack one as well. 👍

[sbaidon]

Just opened up a PR with the rewrite for HMR #1439, tried to change as little as possible, I focused on making the examples consistent with the Development guide

[skipjack]

@TheDutchCoder I'm going to take a stab at #1331 and try to hit both _Production_ and _Tree Shaking_. You interested in _Shimming_ or _TypeScript_? _TypeScript_ shouldn't be too bad (basically just a modified version of _Getting Started_ should do) but _Shimming_ might be more complex.

@marioacc you still interested in _Authoring Libraries_? That's another one that shouldn't be too bad -- essentially a rework of _Getting Started_ but using the various additional configuration options (e.g. library, libraryTarget, externals) to ensure the output is a consumable module.

Once we get these last few done, I'll probably do some cleanup on those final _hmmm_ guides and then close this out.

[mtrivera]

@skipjack I can work on the TypeScript one and make it based on _Getting Started_ as you suggested.

[skipjack]

@mtrivera awesome definitely feel free to ping us if you have any questions!

[TheDutchCoder]

@mtrivera please do, I have no experience with TS, so I would make a poor candidate to tackle that topic ;)

@skipjack I'll take a look at Shimming and see if it's a topic I could cover. If not, I'll let you know and maybe someone else can help us out.

[skipjack]

@TheDutchCoder sounds good and if we don't hear back from @marioacc soon, feel free to take a look at _Authoring Libraries_ too. That one shouldn't be as tough as _Shimming_.

[marioacc]

@skipjack, I have been busy. But I still want to finish it, if there is no problem of course.
Thank you also for giving an example of how to do it, I was a little lost

[skipjack]

I have been busy. But I still want to finish it, if there is no problem of course. Thank you also for giving an example of how to do it, I was a little lost.

Sure no problem and yeah we'd still be thrilled if you wanted to tackle it. My main concern is to just keep this issue moving so we can close it out soon and move on to reviewing and cleaning up other sections of the site. So I don't mean to put any pressure on you but the sooner the better. Even if you just get a rough draft going and would like feedback, feel free to ping @TheDutchCoder and I for review and we can help you get it to completion!

[marioacc]

Just opened a PR 1532.
I focused to explain a little more as well to add enough content for the examples to be able to run.
Also added a warning for the actual bug in the issue 4824

[scottdj92]

I've also been asked a few questions regarding specific plugins, maybe having a section about how to actually implement the topics in "Build Performance" would be good.

[skipjack]

Ok it's just _Shimming_ left of the core guides. May pick it up if no one else beats me to it. Once that's complete I think we can close this out, I'll address those other remaining guides at the end of the list when I start working on #438.

[skipjack]

Started rewriting _Shimming_. Shooting to have a PR submitted by tomorrow.

[skipjack]

We did it! Thanks to everyone who helped 🎉 . I'll take a look at the other non-core guides from the list as I start to work on #1519:

• Migrating Versions (_differs from normal guides_)
• Build Performance (_differs from normal guides_)
• Environment Variables (_consider dropping or moving elsewhere_)
• Development - Vagrant (_hmmm_)
• Dependency Management (_hmmm_)
• Public Path (_consider dropping or moving elsewhere_)
• Integrations (_hmmm_)

If anyone who helped here wants to continue contributing to this cleanup/synchronization effort please take a look at #1386 or comment on #1519.