Extension:RenderBlocking

**MediaWiki extensions manual**
RenderBlocking; Release status: beta
Implementation	User interface
Description	Allows interface administrators to specify render-blocking CSS and JavaScript.
Author(s)	PetraMagnatalk
MediaWiki	1.43+
Database changes	No
	Hooks used BeforePageDisplay;
Licence	GNU General Public License 2.0 or later
Download	GitHub: project page; git repository URL; commit history; ; Note:; No localisation updates are; provided by translatewiki.net.

The RenderBlocking extension allows interface administrators to specify render-blocking CSS and JavaScript.

This extension can be used to heavily modify a wiki's skin without introducing flash of unstyled content (FOUC). For example, interface administrators can completely overhaul the page's DOM with JavaScript before the page is displayed.

Installation

Download and place the file(s) in a directory called RenderBlocking in your extensions/ folder.
Add the following code at the bottom of your LocalSettings.php file:
```
wfLoadExtension( 'RenderBlocking' );
```
Configure as required.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

$wgRenderBlockingInlineAssets: Whether CSS/JS assets should be inlined in the page's <head>. Setting this to true will avoid additional server requests to fetch render-blocking assets, but may result in update delays if the page HTML is cached for an extended period of time. Setting this to false will create a link to the resource in the document's <head> instead.; Default: false.

Usage

For site-wide render-blocking CSS and JavaScript, put them in

MediaWiki:Renderblocking.css
MediaWiki:Renderblocking.js

Note that MediaWiki:Common.css is already render-blocking, so the CSS page is unnecessary and is provided only for the sake of uniformity.

For skin-specific render-blocking CSS and JavaScript, put them in

MediaWiki:Renderblocking-skinname.css
MediaWiki:Renderblocking-skinname.js

In addition to the pages above, a dedicated page specifies more CSS/JS assets to be loaded together as render-blocking:

MediaWiki:Renderblocking-pages
MediaWiki:Renderblocking-skinname-pages

The format is as follows. All pages must be in the MediaWiki namespace.

; Any line not starting with a * will be treated as a comment.
* Pagename.css
* Pagename.js

All CSS/JS assets will be concatenated and minified to produce a single file for CSS and another for JS. If a file is empty, it will not be loaded.

Caveats

Do not assume anything besides vanilla JavaScript is available for render-blocking JavaScript. In particular, do not attempt to use MediaWiki libraries (i.e. mw) and jQuery (i.e. $): they could work under special circumstances but are not guaranteed to be available. To obtain information about the current page, read the DOM. As of MediaWiki 1.45, RLCONF stores data to be used in mw.config and is initialized before JavaScript from this extension is executed. This has been the case for more than 5 years (see the commit introducing RLCONF), though it may be changed without notice and can be risky to depend on.

Do not assume the DOM is fully parsed when a render-blocking script is run. Elements such as document.body may not yet be available. For example, the following snippet may fail with an error Cannot read properties of null (reading 'classList').

console.log(document.body.classList);

To delay the script's execution, you can use the DOMContentLoaded event:

window.addEventListener("DOMContentLoaded", () => {
    console.log(document.body.classList);
});

Debugging

Due to render-blocking scripts loading too early in the document's life cycle, they are harder to debug. The standard debugging parameter ?debug=2 works with this extension. Furthermore, you can use the browser's developer tools to override the content of the network request to the extension's API: this will replace the returned JavaScript code from the server with what you want to test.

Example snippets

Force Vector 2022 to always be in dark mode

This is originally devised on Miraheze.

On MediaWiki:Renderblocking-vector-2022.js, write:

document.querySelectorAll('.skin-theme-clientpref-day').forEach((e) => {
	e.classList.remove('skin-theme-clientpref-day');
	e.classList.add('skin-theme-clientpref-night');
});

Theme wiki pages based on the category

Suppose you want to selectively theme pages based their categories using CSS selectors such as body.category-Extensions_included_in_Miraheze. You can include the following snippet in MediaWiki:Renderblocking.js.

// Otherwise, body may not be found when this js snippet executes
window.addEventListener("DOMContentLoaded", () => {
    RLCONF.wgCategories.forEach((cat) => {
        document.body.classList.add("category-" + cat.replace(/ /g, "_"));
    });
});

Note that this is also possible with the Extension:Gadgets since CSS-only gadgets are render-blocking. However, it will restrict editing category-specific CSS to interface administrators or anyone with the permission to edit gadgets.

This extension is included in the following wiki farms/hosts and/or packages:

Miraheze