aurelia / aurelia/documentation

Extensively document Webpack support and usage in Aurelia

Open
#348 6 comments 3 reactions 1 assignee Claimed by @Vheissu View on GitHub
documentation
Dominant language
No language data
Stars
104
Forks
108
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.