ResourceLoader/Requirements

Requirement Features Benefits Issues
Debugging
Support direct resource inclusion Allows JS resources to be included individually and without being run through the loader software JS resources can be more easily debugged because file names and line numbers correspond to the actual JS resources Requires L10n fallbacks to be embedded in JS resources
Support stand-alone use of loader Allows the script loader system to be integrated into other frameworks or used as a stand-alone service Development efforts can be shared with non-MediaWiki developers, and those developers' efforts can benefit us Makes MediaWiki integration difficult, makes code more foreign to MediaWiki developers
Useful information on loading failure Provides useful, verbose information about failures to load resources Makes development easier Requires more code to be written
Packaging
Remove debug statements Allows JS resources to contain debug information which is stripped out before being sent to the client Debug information can remain in JS resources for future use More moving parts to break
JS/CSS Minification Strips whitespace and comments from JS and CSS resources Reduces the amount of data sent to the client Makes debugging more difficult
JS Closure Compilation Simplifies and aggressively optimizes JS functions Reduces the amount of data sent to the client, and improves the performance of many JS functions Makes debugging very difficult
CSS Janus transformation Flips CSS rules to make LTR stylesheets appropriate for RTL No need to keep separate files around for this if we can apply this transformation in PHP along with the others Makes it slightly more difficult to figure out what the RTL version of a given CSS file looks like
Resource batching / concatenation Multiple resources can be included in a single request Reduces the number of requests from clients Potentially increases cache size, potentially causes double inclusion of resources
Parameterize batched loading Set a URL param to indicate we need resources for a certain combination of prefs/logged-in-ness rather than detecting this on the server Eliminates the need for uncacheable-for-logged-in-users Vary: Cookie responses Increases the number of URL variants
Web-server-level resource caching Caches processed (localized, minified, etc.) scripts on the server Makes it faster to batch resources in different combination Caching is not free, it takes time and space
Use short client-side expiry times Tells clients to refresh cached resources in short intervals (~1h) Eliminates the need to expire HTML (expensive) to force clients to refresh resources Requires that RL requests be cheap, so they should support 304 and be cached in Squid
Use highest-timestamp versioning scheme Version each RL request with the highest last-modified timestamp of the resources involved, formatted in ISO 8601 and rounded to 10s No more manual style versions. 10s rounding and human-readable format allows faster and easier purging of bad resources from Squid May cause conflicts when new JS is served with old HTML, need to code around that in JS
In-place localization Includes localized messages directly within JS resources Allows i18n of JS software without adding additional requests Mixes i18n work with development work
Localization API Makes messages available on demand individually or in groups Provides yet another option for getting L10n to the client Very inefficient way to get L10n to the client
Separate message resource system Generates JS blobs for l10n separately, stores them in the DB Only relevant JS is regenerated when a message changes Makes stand-alone usage more difficult
Export user preferences to JS
CSS grouping (without JS)
CSS includes registered in JS namespace Allows JS resources to check existence of CSS resources and require CSS resources to be loaded before proceeding Fewer CSS resources need to be included initially and modules can safely avoid re-loading already-loaded CSS resources Requires more code to be written
Resource buckets Allows resources to be grouped into buckets such as "all", "view", "edit", etc. Reduces number of individual requests needed Potentially too many things will get put in these buckets
Runtime loading of JS and CSS Allows resources to be included dynamically Reduces the initial payload sent to clients Potentially presents delay between user action and resource availability
Module based loading Resources are identified by module names Provides a standard way of expressing requirements and checking what resources are already loaded
Module loaders Modules each have associated loader functions which are executed to load the module Provides more flexibility in loading Increases the amount of code sent to the client and level of complexity in development
Configurable URL scheme Allows flexibility in request URL formats Makes using a localhost, web-server or CDN a matter of configuration
Allow version aliasing In the case that a buggy version of a script is released, a version redirect can be put in place Avoids purging PHP generated HTML to resolve JS bugs Potentially introduces level of indirection causing negative performance impact. Not needed if scripts are versioned and cached in Squid
Dependency order preservation Allows dependencies to automatically be included in a specific order if needed Makes dependencies simpler to use May make dependency specification more complex
Structure
Clear division of libraries Makes JS resources communicate with each other using well documented APIs Improves the re-usability of JS resources Takes more time to develop and document
Control a specific JS namespace Specifies a unified naming convention and access point for JS resources Improves maintainability and reduces difficulty to learn the system Requires porting existing code to conform
Control naming between PHP and JS resources Specifies clear naming between PHP extensions and JS modules Improves maintainability and reduces difficulty to learn the system Requires porting existing code to conform
Package-level dependency resolution JS modules can form packages, which can then be required/included as a whole Reduces complexity of specifying requirements making development easier Reduces specificity of requirements potentially causing resources to be loaded that will not be used
Map files, buckets and dependencies in PHP Have an associative array structure in PHP that defines objects, which optionally contain a file and optionally have dependencies Makes for fewer distinct URLs (?), which eases caching and purging Limited support for JS-based conditions, would have to be done through parameterization, cannot scale to user scripts
Division between loading and execution JS modules can be loaded on demand, and executed independently Makes dependencies simpler to use Makes writing modules more complex
Allow explicit re-loading Resources are not loaded more than once by default, but can be re-loaded if desired Makes overwriting/re-loading possible/easier
jQuery should be the primary way of extending functionality
jQuery plug-ins should be centrally organized All jQuery plug-ins should be committed to a central place, with version numbers in their names Makes sharing plug-ins easier / more likely to happen and everyone benefits from bug-fixes equally Causes issues with maintaining extensions or if people cloud the plug-in folder with low-quality plug-ins
JS module version conflict management Makes module version information available to JS resources Makes it possible to migrate to newer versions of plug-ins over time Sends more data to the client, adds complexity to configuration
Utilities
JS localization functions JS facilities for handling 18n functionality such as {{PLURAL}} and $ replacement Messages can be more flexible and reusable Must be maintained in parallel with PHP i18n functions, limitations must be well understood by translators

Sources

edit

This document is a synthesis of the following sources