Guides - Review and Simplify #1258
Comments
|
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. |
|
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. |
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. |
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.
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.
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. |
@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:
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. |
skipjack
changed the title
|
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 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:
|
|
Output Management does describe the 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. |
|
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. |
|
Ok so an update:
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 👍 . |
|
@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 . |
|
@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. |
|
Go for it, I'm bogged down with other stuff right now. |
|
Ok I will at least ping you for reviews if that's alright. Your comments on #1338 were very helpful. |
|
Sure, happy to review! Sorry I couldn't have contributed more. |
|
Also: we should update our guides examples to use webpack 3, as it will be installed on an |
|
@mtrivera awesome definitely feel free to ping us if you have any questions! |
|
@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. |
|
@skipjack, I have been busy. But I still want to finish it, if there is no problem of course. |
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! |
This adds a solid baseline for how to start improving build performance with specific pointers for development and production. It can be built on in other PRs but probably doesn't need to be synchronized with the earlier guides (as it's a lot of one off changes that depend on your use case).
|
Just opened a PR 1532. |
This continues our work #1258 and resolves the issues mentioned in #1331. The updates to tree-shaking were more just clean up and synchronization while production included more significant changes and a strong recommendation of `webpack-merge`. The old guide pointed out that _you could_ just maintain two separate configs and duplicate the overlap but I don't think we should recommend this. Resolves #1331
Make some minor updates for consistency with the other guides such doing full `diff` blocks and displaying file names directly above examples. Also removed the conclusion as the next guide is not really a logical next step. Things just get kind of random after this guide (something we'll try to clean up at the end of webpack#1258).
Rework and synchronize the TypeScript guide with the others (see #1258). It now stems from _Getting Started_.
|
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. |
Rewrite the _Author a Library_ guide in accordance with the discussion from #1258. This means using the same style of writing and providing detailed examples.
|
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. |
|
Started rewriting Shimming. Shooting to have a PR submitted by tomorrow. |
Rewrite the main sections of the guide to synchronize it with the other core guides. Briefly mention the other utilities that don't require full on examples (details can be found via links). Closes #1258
|
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:
If anyone who helped here wants to continue contributing to this cleanup/synchronization effort please take a look at #1386 or comment on #1519. |
* docs(api): minor fix in cli Make minor fix in the CLI documentation to reflect this comment: webpack#1577 (comment) * docs(plugins): clarify and simplify `SourceMapDevToolPlugin` docs (#1581) Try to resolve the confusion from #1556. Also update the options section to clean things up a bit both for readability and grammar. Resolves #1556 * docs(guides): update "external limitations" example in author-libraries (#1583) * docs(plugins): update commons-chunk-plugin.md (#1560) Changed example to declare the plugin within `plugins` property. * docs(guides): rewrite shimming (#1579) Rewrite the main sections of the guide to synchronize it with the other core guides. Briefly mention the other utilities that don't require full on examples (details can be found via links). Closes #1258 * docs(guides): fix small issues in shimming (#1591) * docs(guides): fix entry path in typescript (#1592) * docs(guides): fix typos in production (#1584) * fix(sponsors): update to reflect opencollective change (#1588) OpenCollective's structure changed a bit. This address that and makes a few other notable changes: - add additional sponsors - allow to merge additional sponsors to existing sponsors - limit width of logos to 3 x height to disallow very wide logos - format money values with commas * docs(config): update configuration-languages (#1590) Remove local type def from TypeScript snippet. The @types/node type definition module already declares `__dirname` type: https://git.io/v5Dr9 * docs(guides): update hot-module-replacement (#1539) Add an example to demonstrate using hot module replacement with `webpack-dev-server`'s Node.js API instead of within a normal configuration file. * docs(guides): update development.md (#1586) The article was missing references to `clean-webpack-plugin` in the `webpack.config.js` file and `package.json` files. * docs(guides): update tree-shaking.md (#1589) As a conclusion, I thought it would be a good idea to show case a high-level explanation of why it's called tree shaking. Once the user reads the guide and ends up with a high-level explanation the word tree shaking will stick to the user's head. * docs(guides): update code-splitting (#1585) Suggest solutions to the problem right away seems to be a better approach. Use similar text as was used here: https://webpack.js.org/api/module-methods/#import- * docs(plugins): update module-concatenation-plugin (#1565) Add more information about optimization bailouts. Attempt to transfer content from the blog post to the official docs. I want to follow up with a PR for better bailout reasons. The hope is that the reasons will match those listed in the table. * docs(api): fix type in compiler.md (#1601) * docs(config): update output.md (#1541) Clarify interactions between `libraryTarget` and `library`. The interactions between the two and how some of the sections were not well explained, in some cases were incorrect, misleading or missing information. * docs(api): add concurrent usage warning in node.md (#1599) * docs(guides): update environment-variables (#1549) Add documentation about setting environment variables in CLI with `--env`. Link to webpack _CLI Environment_ section. Add additional usage to `--env` CLI docs. * Swap ordering of pre/post loaders (#1602) `pre` loaders run at the beginning, `post` loaders run at the end. * docs(sponsors): update segment's donations (#1603) * update contributors
* update /content/loaders & /content/plugins * docs(api): minor fix in cli Make minor fix in the CLI documentation to reflect this comment: webpack#1577 (comment) * docs(plugins): clarify and simplify `SourceMapDevToolPlugin` docs (#1581) Try to resolve the confusion from #1556. Also update the options section to clean things up a bit both for readability and grammar. Resolves #1556 * docs(guides): update "external limitations" example in author-libraries (#1583) * docs(plugins): update commons-chunk-plugin.md (#1560) Changed example to declare the plugin within `plugins` property. * docs(guides): rewrite shimming (#1579) Rewrite the main sections of the guide to synchronize it with the other core guides. Briefly mention the other utilities that don't require full on examples (details can be found via links). Closes #1258 * docs(guides): fix small issues in shimming (#1591) * docs(guides): fix entry path in typescript (#1592) * docs(guides): fix typos in production (#1584) * fix(sponsors): update to reflect opencollective change (#1588) OpenCollective's structure changed a bit. This address that and makes a few other notable changes: - add additional sponsors - allow to merge additional sponsors to existing sponsors - limit width of logos to 3 x height to disallow very wide logos - format money values with commas * docs(config): update configuration-languages (#1590) Remove local type def from TypeScript snippet. The @types/node type definition module already declares `__dirname` type: https://git.io/v5Dr9 * docs(guides): update hot-module-replacement (#1539) Add an example to demonstrate using hot module replacement with `webpack-dev-server`'s Node.js API instead of within a normal configuration file. * docs(guides): update development.md (#1586) The article was missing references to `clean-webpack-plugin` in the `webpack.config.js` file and `package.json` files. * docs(guides): update tree-shaking.md (#1589) As a conclusion, I thought it would be a good idea to show case a high-level explanation of why it's called tree shaking. Once the user reads the guide and ends up with a high-level explanation the word tree shaking will stick to the user's head. * docs(guides): update code-splitting (#1585) Suggest solutions to the problem right away seems to be a better approach. Use similar text as was used here: https://webpack.js.org/api/module-methods/#import- * docs(plugins): update module-concatenation-plugin (#1565) Add more information about optimization bailouts. Attempt to transfer content from the blog post to the official docs. I want to follow up with a PR for better bailout reasons. The hope is that the reasons will match those listed in the table. * docs(api): fix type in compiler.md (#1601) * docs(config): update output.md (#1541) Clarify interactions between `libraryTarget` and `library`. The interactions between the two and how some of the sections were not well explained, in some cases were incorrect, misleading or missing information. * docs(api): add concurrent usage warning in node.md (#1599) * docs(guides): update environment-variables (#1549) Add documentation about setting environment variables in CLI with `--env`. Link to webpack _CLI Environment_ section. Add additional usage to `--env` CLI docs. * update /content/loaders & /content/plugins * Swap ordering of pre/post loaders (#1602) `pre` loaders run at the beginning, `post` loaders run at the end. * docs(sponsors): update segment's donations (#1603) * fix(fetch): fix some issues when parsing remote content (#1604) The previous regex was a simpler approach to the lead in content issue in fetched plugin/loader readmes, however it wasn't targeted enough to correctly remove all lead in content. The new approach should be a bit more stable but honestly the real fix here would be so better standardize/enforce the readme template before including these packages in the documentation site. I also think we can simplify the template a bit to make the parsing of these readme easier. Resolves #1600 * docs(guides): fix typo in code-splitting (#1606) * docs(config): update `inline` recommendation in dev-server (#1540) Update tip based on discussion in #1540. * docs(config): update pfx description in dev-server (#1595) Clarify the difference between using `pfx` via the command line and in a configuration. * docs(config): clarify stats option sort and default (#1596) * docs(config): add before/after hook info to dev-server (#1608) * docs(guides): fix typo in development (#1609) * docs(guides): fix typo in production.md (#1610) * docs(readme): fix typos (#1615) * fix(markdown): fix issue with multiple pipes in a single cell (#1611) Introduced better fix for pipes escaping in Markdown table cells. * docs(guides): update hot-module-replacement (#1614) Second argument of `server.listen` is a hostname, in this context, `'localhost'`. The third argument of `server.listen` is the success callback... https://github.com/webpack/webpack-dev-server/blob/master/lib/Server.js#L552 * docs(guides): fix `onClick` instances in caching (#1613) * docs(config): fix typo in module.md (#1618) * docs(guides): fix grammar in getting-started.md (#1619) * docs(config): add filename to index example (#1620) * docs(guides): update wds options in hot-module-replacement (#1617) Define the host property of the options object and set it to 'localhost'. The webpack-dev-server CLI defaults the host to 'localhost', but `addDevServerEntrypoints` from the webpack-dev-server Node.js API does not set a default and leaves it undefined, which will eventually throw "Uncaught SyntaxError: The URL 'http:/sockjs-node' is invalid" in the browser when following the code example. webpack/webpack-dev-server#1129 * fix(sponsors): opencollective api changed, add validation (#1622) * docs(development): update how-to-write-a-loader.md (#1621) Changes `_` to `.` to have correct code. * update /content/loaders & /content/plugins * update contributors * docs(plugins): add deepChildren to commons-chunk-plugin.md (#1625) * feat(sponsors): highlight latest sponsors/backers (#1628) * refactor: update information architecture This commit contains the following changes: - Merge support and development into a coherent "Contribute" section. - Flatten `/api/plugins` in preparation for flattened page `group`ing. - Sort "Contribute" section and rewrite index page using "Why Support?". - Simplify and organize antwar config as much as possible. - Move `title` / `description` fields to the actual components. BREAKING CHANGE: The route restructuring and content reorg breaks some routes. Before this is merged, we should make sure to add redirects for anything broken. * refactor(navigation): update routes and styling Simplify routing to reflect antwar and content changes and remove extraneous links. Simplify styling to first improve the design, but also to provide a lot more breathing room so less hacks are needed for smaller page sizes. With the updated design we should have room for "Voting" and "Analyze" links once those micro apps are in a better place. * fix: add link to starter kits "Support" is now included in the "Contribute" section and already has a link in the top navigation. The starter-kits page was previously hidden from users, so this exposes it a bit more. * refactor(navigation): update the navigation component Make minor styling change for consistent gutter. Extract link data into a separate JSON file. Update variable and parameter names for clarity. * feat: allow page grouping within sections via `group` field Add support for a new `group` field in each page's YAML frontmatter to group pages together in an intuitive way. The benefit of this approach vs directories is that changing a pages group within the same top-level section won't affect its route and thus will not break links to it. * style(page): align content better on larger screens * docs: remove empty pages * docs(contribute): add writers-guide and update release-process * docs: sort the base pages more intuitively * docs(api): update page names and grouping * fix(mobile): clean up mobile sidebar data * docs(api): clean up formatting and fix linting errors * docs(api): fix markdown listing issues * docs(contribute): fix markdown linting issues * docs(api): rewrite the index page * docs(api): minor formatting and cleanup * docs: add redirects for all broken routes The changes in #1612 break a significant amount of pre-existing URLs, this commit adds redirects for everything I could see that would be broken. * style(page): fix small padding issue The padding here is useful for browsers that display a full on scrollbar instead of an overlay scrollbar. We can continue to think about how that space it utilized in future commits/prs. * docs(guides): update production.md (#1629) Modify the doc accordingly to the following tweetstorm where Dan Abramov & Sean Larkin kindly explained this to me. https://twitter.com/TheLarkInn/status/917524723579338752 * fix(markdown): wrap inline code (#1634) This change makes inline code blocks wrap so long lines will not be hidden outside paragraph. Resolves #1633 * docs(guides): fix small typo excluding closing brace (#1637) * docs(guides): fix typo in development.md (#1638) * docs(guides): update hot-module-replacement.md (#1639) Maintain consistent code from previous guide (development). * docs(guides): maintain consistent code in production.md (#1640) * docs(guides): update typescript.md Configure TypeScript to compile modules to ES2015 module syntax, enabling webpack to resolve the `import` / `export` syntax on it's own. With this included, the only thing necessary to enable _tree shaking_ is the inclusion of the `UglifyJSPlugin` (which I'm not adding to this article as it is just centered on getting started with TypeScript). Resolves #1627 * update /content/loaders & /content/plugins * fix LinkDropdown * 修复 npm 命令错误导致编译不成功的问题
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
importexample will actually result in webpackJSONp errors and create a0.bundle.jsfile 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 😄
The text was updated successfully, but these errors were encountered: