Instant Diffs

Instant Diffs (ID) is a free open-source JavaScript tool that enhances MediaWiki diff links with interactive functionality — dynamically loaded content via AJAX technology in dialog windows. It enables users to interact with diffs and revisions directly within the page, rather than being redirected to a separate page. These features are integrated not only into all core interface pages where revision diffs are linked, like local and global watchlists, user contributions, recent changes and new pages, but also into user-contributed content. The minimal required version of MediaWiki is 1.35, but it is strongly recommended to upgrade to at least 1.43 LTS.

Features

• Displays an action button (❖ for diffs or ✪ for revisions) after the link to open the Instant Diffs dialog. By default, the click action is added directly to the link, but you can still open the link in the current tab using Alt+Click.
• Displays an action button (➔) after the link to navigate to the page and section where the edit was made. If the Convenient Discussions script is installed, the button will also try to navigate to the corresponding comment.
• Allows quick switching between a revision view and its comparison (diff) with another revision.
• Provides an Actions menu in the dialog, allowing you to copy links (including internal wiki links), navigate to the page, its history, or discussion, and add or remove the page from the watchlist.
• Allows adding custom actions to the Actions menu through a flexible API. See the Developer guide.
• Enables viewing diffs and revisions from foreign interwikis in the GlobalContributions, GlobalWatchlist and in edits from Wikidata.
• Supports keyboard shortcuts for navigation between diffs and between links on the page in the Instant Diffs dialog window.
  • Arrow Left - previous diff or revision in the history;
  • Arrow Right - next diff or revision in the history;
  • Ctrl+Arrow Left - previous link on the page;
  • Ctrl+Arrow Right - next link on the page;
  • Ctrl+Arrow Up - switch between revision view and its comparison;
  • Ctrl+Arrow Down - toggle visibility of the actions menu.
• Allows sending thanks, patrolling, and rolling back (with confirmation prompts enabled) directly from the dialog.
• Enables administrators to view hidden revisions directly in the dialog without any additional steps. The suppressrevision user right is required to access hidden revision content.
• Fully adapts to mobile devices, especially optimized for the Minerva Neue skin.
• Offers a wide range of customization settings that are saved globally across all Wikimedia projects.
• Provides flexible configuration for the deployment script locally. See available deployment configuration options here.

Development

Install Node.js and package dependencies:

npm install

Make a copy of the environment variables file, configure your project, and fill in all necessary fields:

Unix:

cp env.json.example env.json

Windows (PowerShell):

Copy-Item env.json.example env.json

Configuration Parameters

The env.json file contains configuration objects for different deployment environments. Each configuration object (e.g., testwiki, mediawiki) supports the following parameters:

Parameter	Type	Default	Description
dir	string	required	Directory containing the built files (e.g. dist)
name	string	required	Base name of the script (e.g. instantDiffs)
server	string	required	MediaWiki server URL (e.g., https://www.mediawiki.org)
scriptPath	string	required	MediaWiki script path (e.g., /w)
target	string	required	Target page on the wiki where the script will be deployed. Use the $name placeholder for the script name (e.g., MediaWiki:Gadget-$name)
i18n	string	required	Target path for internationalization files. Use the $name placeholder for the script name (e.g., MediaWiki:Gadget-$name-i18n/)
i18nDeploy	boolean	true	Whether to deploy external language files. Automatically set to false in development mode (--dev flag)
i18nBundle	string[]	["en"]	Array of language codes to bundle with the main script. English (en) is always included even if not specified
legalDeploy	boolean	true	Whether to deploy legal notice files
rateLimit	number	0	API rate limit in requests per minute. Set to 0 for no rate limiting
retries	number	0	Number of retry attempts for each failed individual request
credentials	object	{}	Authentication credentials for siddharthvp/mwn library (Interface MwnOptions). Typically includes username, password, and userAgent
esbuild	object	{}	Optional build configuration for esbuild. Passed to the esbuild.build() function (e.g., { "target": "es2016" })

Deployment Commands

To start a local development server (uses the local project configuration from env.json):

npm run start:local

Or specify a custom project configuration name:

cross-env PROJECT=local npm run start

To deploy to a wiki, specify the project configuration name (e.g., mediawiki):

cross-env PROJECT=mediawiki npm run deploy

Define a gadget

If you deploy the script as a gadget, remember to define the gadget in your wiki's MediaWiki:Gadgets-definition page with a configuration like this:

* instantDiffs [ResourceLoader | dependencies=site, mediawiki.api, mediawiki.util, mediawiki.storage, mediawiki.notification, mediawiki.Title, oojs] | instantDiffs.js | instantDiffs.css

If you want to preload a language other than English, link the language file to the end of the definition, for example:

instantDiffs.js | instantDiffs.css | instantDiffs-i18n/uk.js

See also

• Documentation
• News
• Feedback
• Developer guide
• Translations

---

Support Ukraine