Extensively document Webpack support and usage in Aurelia

Vheissu commented 7 years ago

Aurelia has had support for Webpack for some time now. Unfortunately, it isn't well documented for newcomers and experienced developers like. This issue is for tracking documentation pertaining to Aurelia and Webpack usage.

Subjects documentation should cover:

Why Webpack?

We have JSPM and RequireJS that developers can already choose from, what reason would a developer have for choosing Webpack? An explanation of Webpack's philosophy, how it sits in the ecosystem alongside other choices and so on.

Getting an Aurelia application up and running with Webpack

At present, Webpack is only supported via the skeleton-navigation project structure. In future, the CLI will support generation of all supported platforms including Webpack. An example of getting Webpack running with Aurelia from scratch as well as all existing solutions should be documented.

Configuring Webpack

Webpack is highly extensive and although Webpack v2 ushered in a more streamlined API, the configuration aspect of Webpack is a pain point for new and seasoned developers alike. This needs to be broken into two parts, the Aurelia Webpack plugin itself (which is used by Aurelia to support Webpack) and Webpack configuration for file formats, plugins and more.

Configuring Webpack: Aurelia Webpack Plugin

A custom plugin used by Aurelia to support Webpack properly. It comes with its own configuration options and exposed methods for working with modules and files inside of an Aurelia application.

Configuring Webpack: Webpack Itself

This would touch upon basics of configuring Webpack within the context of an Aurelia application. How to implement minification, optimising bundles, hashing and supporting loaders for popular formats; SCSS, JS, CSS, Autoprefixer and so on. Even though this itself is documented elsewhere, it would reduce developer frustration.

Adding In Polyfills

To get an Aurelia application working in older browsers such as Internet Explorer 10, you need to polyfill missing browser features and API's.

Webpack allows you to intelligently polyfill missing browser features such as Promises and so on using libraries like Bluebird. We need to detail how a user can polyfill a Webpack based Aurelia application.

Lazy Loading

Lazy loading is a feature supported by Webpack that allows a developer to break their application up into smaller, dynamic chunks that get loaded on demand. Thanks to the Aurelia Webpack Plugin, Aurelia supports dynamic bundles via PLATFORM.moduleName() which can allow a developer to create a lightweight Aurelia application that is loaded on demand.

Troubleshooting

When things don't go to plan, we need solid documentation on known caveats of using Webpack and how to debug your way out of them (where user error is not to blame). The end goal here is to document all known traps a user might fall into it, to prevent unnecessary issue creation.

The biggest one to document here is the Unknown Module ID error that users of Webpack will encounter.

Todo

[x] Write "Why Webpack" section.
[ ] Detail getting an Aurelia application using Webpack up and running from scratch. This should include a working example hosted on Gist.run or similar site where code can be seen and run.
[x] Detail configuring the Webpack Webpack Plugin
[x] Detail configuring Webpack itself, working with different module formats and other basic tasks
[ ] Detail adding in polyfills and working with plugins such as imports-loader, exports-loader and so on where applicable
[ ] Detail lazy loading aspect of Webpack
[ ] Detail troubleshooting Webpack errors and navigating known caveats to be aware of.
[ ] To compliment the extensive documentation, we should have a range of different example applications showcasing aspects such as dynamic bundle loading and different configuration options provided by the Aurelia Webpack Plugin.

Vheissu commented 7 years ago

Work has begun on the webpack aspect here: https://github.com/aurelia/documentation/blob/master/docs-v2/drafts/introduction/getting-started/webpack.md - still refinements and additions to be made.

Vheissu commented 7 years ago

A linked README has been created inside of the docs folder I've been working within. It contains an easier way to see documentation in progress or written: https://github.com/aurelia/documentation/tree/master/docs-v2 - the Webpack story is getting well documented now.

jods4 commented 6 years ago

Core Webpack docs need to be updated for the new plugin. Related: aurelia/webpack-plugin#147

chrisckc commented 5 years ago

As i have already seen mentioned here, the webpack documentation is out of date.

I have just had a look at this: https://aurelia.io/docs/build-systems/webpack

This has changed in webpack v4 with the introduction of splitChunks: https://aurelia.io/docs/build-systems/webpack/bundling#entry-bundles

Is this still relevant? i didn't know that it is possible to specify webpack code splits inside 'aurelia.build' in package.json? https://aurelia.io/docs/build-systems/webpack/bundling#code-splitting-chunks-async-bundles

The documentation talks about the skeleton, but does not seem to match the current state of the webpack skeleton:

For this very reason, the skeleton-navigation example uses a package called Easy Webpack https://aurelia.io/docs/build-systems/webpack/bundling#bundle-configuration-and-easy-webpack

The skeleton does not use that plugin, the plugin is very old (in the js world anyway) , last release 2 years ago: https://github.com/easy-webpack/core/releases

EisenbergEffect commented 5 years ago

Thanks for catching this @chrisckc I believe @fkleuver is going to pick this up and update the docs with a simple "from scratch" configuration for Webpack for those who don't want to use our CLI.

fkleuver commented 5 years ago

@chrisckc @EisenbergEffect Here's a first draft: https://github.com/aurelia/documentation/pull/368

Instead of extensively documenting webpack, I would propose the opposite: keep it simple, and refer to the official webpack documentation for advanced scenarios. Truth is that most things aren't specific to Aurelia and any effort we put into documenting them would be duplicated. Consequently there will be less docs for us to maintain and they'll be easier to keep up-to-date.

Thoughts?

aurelia / documentation