An alternative frontend workflow for extensions
This epic explains and proposes an alternative workflow for frontend development on extensions.
Explicit and mandatory goals of the workflow are:
- Remain fully compatible with mediawiki core and ResourceLoader
- Be an optional workflow that can be adopted per project or extension with front-end assets
- Rely on widely used and maintained (only) open source leveraging the broader OSS community
- Achieve the goals listed in the Goals section
A proof of concept implementation is provided for the isolated and small MediaWiki-extensions-Cards, see the How section. Out of scope are the reasons for existence of such extension, it is just used as test bed.
Why
- Manual configuration of extension.json ResourceModules ends up being big, very complex and error prone (ex. 1700 lines on MobileFrontend). Hard to modify, optimize, and it has caused non-deterministic JS exceptions due to misconfigurations (ex. T146031 T145566 T99461).
- Slow, integrated (requiring mediawiki install) unit tests, that are not real unit tests discourage testing practices and coverage.
- Inability to consume and integrate libraries from npm into our source code.
- Inability to use frontend tools from the npm ecosystem.
- Inability to have source maps on production code to diagnose problems.
- Bigger than necessary frontend bundles served to clients due to out of date minifier on the bundle
- Performance hit of having to compile templates on clients
Goals
- Reduce manual configuration of dependencies of modules to avoid misconfiguration and non-deterministic JS failures
- Enable the possibility of consuming JS libraries from npm
- Precompile templates instead of sending a compiler and text templates and compiling them in client browsers
- Minimize size of front-end assets sent to the client by using up to date tools like uglify
- Have source-maps mapping to the original sources both in development and production
- Being able to run front-end unit tests fast and quickly in a node environment, and enable the possibility of doing TDD while developing
What
Use a node based asset bundler to realize the frontend dependency graph and bundle it, instead of relying on manual configuration in a JSON file.
Main choices because of usage and support are browserify and webpack. Both being good choices, webpack has been chosen because of it's batteries-included approach.
How
- Introduce webpack bundler
- JS file loading with common.js
- Minification using latest npm's uglify
- https://gerrit.wikimedia.org/r/#/c/312499/
- Add source-maps for development and production
- Introduce CI check to check that built assets have been commited properly
- Move JS assets to the webpack pipeline
- Move mustache templates to the webpack pipeline
- Precompile templates at build time instead of at runtime
- https://gerrit.wikimedia.org/r/#/c/312508/
- Introduce node based unit test runner and configure npm scripts
- Migrate cards unit tests to run on npm test
Post-implementation work
- Enumerate bundle sizes pre-post migration, configuration simplification, test workflow improvements
- Create epic for folding cards work and workflow into related-articles extension.