-
-
Notifications
You must be signed in to change notification settings - Fork 110
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Extensively document Webpack support and usage in Aurelia #348
Comments
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. |
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. |
Core Webpack docs need to be updated for the new plugin. |
As i have already seen mentioned here, the webpack documentation is out of date. I have just had a look at this: This has changed in webpack v4 with the introduction of splitChunks: Is this still relevant? i didn't know that it is possible to specify webpack code splits inside 'aurelia.build' in package.json? The documentation talks about the skeleton, but does not seem to match the current state of the webpack skeleton:
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 |
@chrisckc @EisenbergEffect Here's a first draft: #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 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
imports-loader
,exports-loader
and so on where applicableThe text was updated successfully, but these errors were encountered: