Wikimedia Performance Team/Page load performance

This document describes which aspects of a web page impact page load performance, and how changes can influence those aspects. This was originally drafted in February 2016 (T127328) and was revised in October 2018.



We primarily focus on the following three metrics:

  • Visual rendering: Most of the page should render to completion as quickly as possible. Observed through the Paint Timing API (first-contentful-paint).
  • Total page load time: The load indicator in web browsers. This waits for the download and rendering of HTML document and the download and initial execution of all sub resources (JavaScript, CSS, images). Observed through the Navigation Timing API (loadEventEnd).
  • Responsiveness: The page should be able to respond to user interaction at all times. There should not be background or periodic code execution that causes lag or freezing of the main thread for prolonged periods of time. Observation through the Long Tasks API.


Performance principles, in order of their importance:

  1. User. (Perceived performance and overall user experience. This includes backend latency response times.)
  2. Developer. (Developer productivity; ease of learning, maintaining, and debugging.)
  3. Server efficiency. (Such as disk space, memory usage, CPU load, number of servers, etc.)

Shipping frontend assetsEdit

The page loading process for MediaWiki.

Deliver CSS and JavaScript fast (bundled, minified, and avoiding duplication) while retaining the benefits of caching. This is all done for you by ResourceLoader.

See ResourceLoader/Developing with ResourceLoader for how to register your CSS and JavaScript files as module bundles in MediaWiki, and how to load those bundles on any given page.

HTTP cachingEdit

Improving the cachability of responses to web requests used in the critical path, is expected to have the following impact:

  • First views: None.
  • Repeat views:
    • For any resource:
      • Consume less bandwidth (reduces mobile data costs).
      • Consume less power (fewer cell-radio activations required).
    • For CSS files:
      • Reduce time for visual rendering. Cached stylesheets load faster without a network roundtrip, allowing rendering to start and/or complete sooner.
      • Reduce time to domComplete and loadEventEnd metrics. Stylesheets are subresources required for DOM completion.
    • For JavaScript files:
      • Reduce "Time to Interactive". Cached scripts take less time to load, parse, and compile. Browser may store the compiled bytecode from previous page views. As of writing (Dec 2019), the bottleneck in loading JavaScript code is often not the download or execution, but the parsing/compilation. Allowing this to be cached or reducing the amount of code can benefit the user more than optimising how fast it can execute.


Reduce the time it takes for the browser to receive the response to a request it makes.


  1. Making the response complete sooner. For example:
    • … by improving backend response times on the server,
    • … by allowing the response to be cached by the CDN in a nearby datacenter,
    • … by reducing the size of the response.
  2. Making the request start earlier. For example:
    • … by making requests in parallel instead of serially one-after-the-other.
      • If same code is in charge of multiple requests, the $.when() function can be used to make parallel requests.
      • If multiple pieces of code are in charge of their own requests, consider returning a Promise and letting the other code proceed immediately to make its own request. Then, only once you truly need the data from the first Promise (or to wait for its response) and call its then() method. You can also use $.when() to return a Promise that auto-resolves when multiple other Promises have settled.
    • … by hinting the browser directly about your intentions. This has the benefit of not needing any changes to your code! By the time your HTML, CSS, or JS, makes a related request, the result of these hints will automatically be used.

Impact on first views and repeat views:

  • Reduce time overall (for the feature to load, or for the action to be performed).
  • Consume less power (making more optimum use of the network means less idle time and thus fewer cell-radio activations required).


Avoid using rel="preload" links or headers on the main HTML navigation response as this can cause congestion and competition against the HTML resource itself, as well as the critical CSS resources needed for initial rendering. In MediaWiki these resources are already linked from the <head> and discovered and pre-fetched as soon as possible, by the browser's lookahead parser.

To start the download of late-discovered resources earlier than usual, consider preloading closer to the time they are needed to avoid this competition.

How to:

  • Dynamically create an element like <link rel="preload"> in JavaScript, based on a user interaction toward the feature/resource.
  • Emit Link: rel=preload headers on a resource that is between the HTML and the resource in question.

For example, in MediaWiki we generally display the logo as a CSS background image on a particular <a> element. The image is specified by a stylesheet. When the browser parses and applies this stylesheet, it ignores the url because the CSS rule in question does not apply yet. (Rules are only applied if the rule matches the state of an element in the DOM, and when the browser first renders an article it typically has not yet reached the HTML of the sidebar).

The "natural" point where the browser will start the download for the logo file is when that sidebar HTML has been reached and rendered to the user (first without logo). In order to optimise this, the skin stylesheet emits a Link: rel=preload header that hints the browser to start the download immediately because we know we are going to need it soon, even if the brower hasn't reached that part of the HTML stream yet.

Size of HTML payloadEdit

The first 14 KB (per TCP slow-start), should ideally contain everything needed to render the skin layout and a little bit of the article text. And, it should allow the browser to render that initial layout in a way that isn't later moved around or otherwise invalidated (additional components may appear later, but existing components should not move).

Examples of how to improve this:

  • Reduce amount of per-page header bloat, e.g. <link> tags, RLQ, mw.config, mw.loader.
  • Better minification for inline CSS, inline JavaScript and HTML within the <head>.
  • Arranging the HTML to ensure layout and start of content render first.

See also T231168 for on-going work in this area.

Size of stylesheetsEdit

Reducing the size of the main (blocking) stylesheet loaded by the HTML, is expected to have the following impact:

  • All views (first view, and repeat views):
    • Improvement of all paint metrics. Smaller stylesheets load and parse faster, allowing rendering to start and complete sooner.
    • Reduce time to domComplete and loadEventEnd metrics. Stylesheets are subresources required for DOM completion.
    • Consume less bandwidth (reduces mobile data costs).
    • Consume less power (reduce CPU time for stylesheet parsing, especially data URIs. See T121730 for on-going work).

Size of scriptsEdit

Reducing the amount of code contained in the startup module and reducing the number and size of modules queued directly onto a page by addModules().

Expected impact on all views (first view, and repeat views):

  • Reduce "Time to Interactive". Less code to download, parse, and execute.
  • Reduce time to domComplete and loadEventEnd metrics. These scripts are sub resources part of DOM completion.
  • Consume less bandwidth (reduces mobile data costs).

(The above does not apply to scripts that are lazy-loaded after document-ready from a user interaction.)

The scripts run in three major phases. These run serially, which means earlier phases naturally have a bigger impact when improved because it allows subsequent phases to start their work sooner:

  1. Inline scripts in HTML <head> (including page configuration, page module queue, and the async request to the Startup module).
  2. The Startup manifest (including module registry, dependency tree, site configuration, and the mw.loader client).
  3. The page modules (the source code of modules loaded on the current page, and their dependencies).

Processing cost of scriptsEdit

Reduce the amount of time spend in executing JavaScript code during the critical path. This includes:

  • Deferring work that does not need to happen before rendering.
  • Splitting up work in smaller idle-time chunks to avoid blocking the main thread for too long (non-interactive "jank").
  • Re-arranging code so that there are no style reads after style writes in the same event loop. The browser naturally alternates between a cycle of JS execution and a cycle of style computation and rendering. If styles are changed in the main JS cycle and then read back within that same cycle, the browser is forced to pause the script and perform an ad-hoc render cycle before being able to resume the script. See also:

Expected impact on all views:

  • Reduce "Time to Interactive". Less execution before the page is ready. Less uninterrupted execution which blocks interactions Fewer "forced synchronous layouts" which significantly slow down code execution.
  • Reduce time to loadEventEnd metrics. These finishing of initial scripts' execution holds back "loadEvent".