Requirements

Before installing Citizen, ensure your environment meets these requirements.

MediaWiki Version

Citizen requires a modern version of MediaWiki to take advantage of the latest features and APIs.

Current requirement: MediaWiki 1.43.0 or later

This requirement is defined in skin.json:

skin.json

{
  "name": "Citizen",
  "version": "3.14.0",
  "requires": {
    "MediaWiki": ">= 1.43.0"
  }
}

Why MediaWiki 1.43.0?

Citizen leverages features introduced in recent MediaWiki versions:

SkinMustache - The modern skin base class
Codex v1.14.0+ - Design system components used throughout the skin
ResourceLoader improvements - Better module loading and dependency management
Modern PHP features - Type declarations, native types, and strict typing
Vue 3 support - For reactive components like the command palette

Legacy Versions

If you’re running an older version of MediaWiki, you can use a legacy version of Citizen:

Legacy versions receive limited support. Consider upgrading MediaWiki to use the latest Citizen features.

Citizen Version	MediaWiki Version	Status
3.x (latest)	1.43.0+	✅ Actively developed
2.40.2	1.39.4 – 1.42.7	⚠️ Legacy support
1.17.9	1.35.2 – 1.39.3	⚠️ Legacy support

Installing Legacy Versions

Manual
Git
Composer

Download the specific release:

# For MediaWiki 1.39.4 - 1.42.7
wget https://github.com/StarCitizenTools/mediawiki-skins-Citizen/archive/refs/tags/v2.40.2.zip
unzip v2.40.2.zip
mv mediawiki-skins-Citizen-2.40.2 skins/Citizen

Clone and check out the specific tag:

git clone https://github.com/StarCitizenTools/mediawiki-skins-Citizen.git skins/Citizen
cd skins/Citizen
git checkout v2.40.2  # Or v1.17.9 for older MW versions

Specify the version in your composer.local.json:

composer.local.json

{
  "require": {
    "starcitizentools/citizen-skin": "2.40.2"
  }
}

Then run:

composer update --no-dev

PHP Requirements

Citizen follows MediaWiki’s PHP requirements:

PHP 7.4.3+ for MediaWiki 1.39.x
PHP 8.0+ for MediaWiki 1.40.x - 1.42.x
PHP 8.1+ for MediaWiki 1.43.0+ (current)

PHP Extensions

All extensions required by MediaWiki are sufficient for Citizen:

json - For JSON encoding/decoding
mbstring - For Unicode string handling
xml - For XML parsing

Citizen uses declare(strict_types=1) in all PHP files and requires strict type support.

Server Requirements

Web Server

Any web server supported by MediaWiki works with Citizen:

Apache 2.4+
Nginx 1.20+
LiteSpeed
IIS 10+

Database

Citizen doesn’t add any database requirements beyond MediaWiki’s:

MySQL 5.7.0+ or MariaDB 10.3+
PostgreSQL 10+
SQLite 3.8.0+

Client Requirements (Browser Support)

Citizen is built for modern web browsers and does not support Internet Explorer.

Supported Browsers

Desktop Browsers

Chrome/Edge 90+
Firefox 88+
Safari 14+
Opera 76+

Mobile Browsers

Chrome for Android
Safari for iOS 14+
Firefox for Android
Samsung Internet

Browser Features Required

Citizen uses modern web features:

CSS Custom Properties (CSS variables)
ES6 JavaScript (arrow functions, const/let, classes)
Fetch API (for AJAX requests)
IntersectionObserver (for scroll-based features)
ResizeObserver (for responsive elements)
localStorage (for preferences)
Service Workers (optional, for PWA features)

Citizen uses the es6: true flag for some ResourceLoader modules and requires ES6 support in browsers.

Browser Compatibility Configuration

The skin’s ESLint configuration defines compatibility:

.eslintrc.json

{
  "extends": [
    "wikimedia",
    "plugin:compat/recommended"
  ],
  "env": {
    "browser": true,
    "es6": true
  }
}

Dependencies

Citizen’s dependencies are automatically managed by MediaWiki’s ResourceLoader.

PHP Dependencies

Defined in composer.json:

composer.json

{
  "require": {
    "composer/installers": "^2|^1.0.1"
  }
}

JavaScript Dependencies

All JavaScript dependencies are provided by MediaWiki or bundled with Citizen:

MediaWiki Core Modules

mediawiki.storage - LocalStorage abstraction
mediawiki.util - Utility functions
mediawiki.api - API client
mediawiki.page.ready - Page ready state

Codex Components

From MediaWiki 1.43.0’s bundled Codex (v1.14.0+):

{
  "codexComponents": [
    "CdxButton",
    "CdxIcon",
    "CdxCheckbox",
    "CdxField",
    "CdxRadio",
    "CdxSelect",
    "CdxToggleSwitch",
    "CdxTextInput",
    "CdxThumbnail",
    "CdxSearchResultTitle"
  ]
}

Citizen uses the Codex version bundled with your MediaWiki installation. The minimum is v1.14.0 (bundled with MW 1.43), but newer MW versions may provide a newer Codex.

Vue and Pinia

Vue 3.4.27+ - For reactive components
Pinia 2.0.16+ - For state management in the command palette

Both are provided by MediaWiki’s ResourceLoader.

Optional Enhancements

These extensions are not required but enhance Citizen’s features.

Recommended Extensions

PageImages (bundled with MediaWiki)

Adds thumbnail images to search suggestion results.

LocalSettings.php

wfLoadExtension( 'PageImages' );

When installed, search results will show page images alongside titles and descriptions.

TextExtracts (bundled with MediaWiki)

Provides short text descriptions for search suggestions.

LocalSettings.php

wfLoadExtension( 'TextExtracts' );
$wgCitizenSearchDescriptionSource = 'textextracts';

ShortDescription

Adds short descriptions under page titles and in search results.

LocalSettings.php

wfLoadExtension( 'ShortDescription' );
$wgCitizenSearchDescriptionSource = 'wikidata';

Install from MediaWiki.org

TemplateStylesExtender

Allows CSS variables in TemplateStyles, including Citizen’s design tokens.

LocalSettings.php

wfLoadExtension( 'TemplateStylesExtender' );

This lets wiki editors use Citizen’s CSS variables in template styles:

.my-template {
    color: var(--color-base);
    background: var(--background-color-base);
}

Install from MediaWiki.org

Styled Extensions

Citizen includes custom skin styles for 70+ MediaWiki extensions. These are automatically applied when the extensions are installed:

VisualEditor

Modern WYSIWYG editing

Echo

Notification system

CodeMirror

Syntax highlighting editor

Semantic MediaWiki

Semantic data management

TabberNeue

Tab interfaces

Cargo

Data storage and querying

Popups

Hover page previews

MultimediaViewer

Enhanced image viewing

DiscussionTools

Modern discussion interface

For a complete list of supported extensions, see the Extension Support page or the README on GitHub.

Development Requirements

If you plan to contribute to Citizen or customize its source code, you’ll need:

Node.js and npm

Node.js 18+
npm 9+

Used for building assets and running tests:

package.json

{
  "scripts": {
    "lint": "npm -s run lint:js && npm -s run lint:styles && npm -s run lint:i18n && npm -s run lint:md",
    "test": "vitest run",
    "preflight": "npm run lint && npm test"
  }
}

PHP Development Tools

For PHP linting and testing:

composer install  # Installs dev dependencies
composer test     # Run linters
composer phan     # Static analysis
composer phpunit  # Run tests
composer preflight # All checks

Development Dependencies

PHP
JavaScript

composer.json

{
  "require-dev": {
    "mediawiki/mediawiki-codesniffer": "50.0.0",
    "mediawiki/mediawiki-phan-config": "0.19.0",
    "mediawiki/minus-x": "2.0.1",
    "php-parallel-lint/php-parallel-lint": "1.4.0"
  }
}

package.json

{
  "devDependencies": {
    "eslint": "8.57.1",
    "eslint-config-wikimedia": "0.32.3",
    "stylelint": "17.4.0",
    "vitest": "^4.0.18",
    "@vue/test-utils": "^2.4.6"
  }
}

Docker Development Environment

The recommended development setup uses MediaWiki’s Docker environment:

# From the MediaWiki root
docker compose up -d
docker compose exec mediawiki bash -c "cd /var/www/html/w/skins/Citizen && composer preflight"

For detailed development setup instructions, see AGENTS.md in the repository.

Performance Considerations

Citizen is designed for good performance, but some features have resource implications:

ResourceLoader Modules

Citizen loads several ResourceLoader modules:

skins.citizen.styles - Base styles (~50KB minified)
skins.citizen.scripts - Core JavaScript (~30KB minified)
skins.citizen.search or skins.citizen.commandPalette - Search functionality
skins.citizen.preferences - User preferences panel (loaded on demand)

CDN and Caching

Ensure your MediaWiki installation has proper caching configured:

LocalSettings.php

// Enable file cache for anonymous users
$wgUseFileCache = true;
$wgFileCacheDirectory = "{$IP}/cache";

// CDN/reverse proxy
$wgUseCdn = true;
$wgCdnServers = [ '127.0.0.1' ]; // Your CDN/proxy IPs

// Resource loader cache
$wgResourceLoaderMaxage = [
    'versioned' => 30 * 24 * 60 * 60, // 30 days
    'unversioned' => 5 * 60 // 5 minutes
];

Progressive Web App

PWA features add a service worker (~5KB):

LocalSettings.php

$wgCitizenEnableManifest = true; // Adds ~2KB manifest.json

Checking Your Environment

To verify your environment meets all requirements:

Check MediaWiki version

Visit Special:Version on your wiki and verify MediaWiki version is 1.43.0+

Check PHP version

php -v

Should show PHP 8.1.0 or later.

Verify file permissions

ls -la skins/Citizen/

The web server user (e.g., www-data, apache) must be able to read all files.

Test in browser

Visit your wiki and check browser console (F12) for any errors.

Next Steps

Install Citizen

Ready to install? Follow the installation guide

View Demo

See Citizen in action on the Star Citizen Wiki

Getting Started

Configuration

Features

Customization

Extension Support

Development

​Requirements

​MediaWiki Version

​Why MediaWiki 1.43.0?

​Legacy Versions

​Installing Legacy Versions

​PHP Requirements

​PHP Extensions

​Server Requirements

​Web Server

​Database

​Client Requirements (Browser Support)

​Supported Browsers

Desktop Browsers

Mobile Browsers

​Browser Features Required

​Browser Compatibility Configuration

​Dependencies

​PHP Dependencies

​JavaScript Dependencies

​MediaWiki Core Modules

​Codex Components

​Vue and Pinia

​Optional Enhancements

​Recommended Extensions

​Styled Extensions

VisualEditor

Echo

CodeMirror

Semantic MediaWiki

TabberNeue

Cargo

Popups

MultimediaViewer

DiscussionTools

​Development Requirements

​Node.js and npm

​PHP Development Tools

​Development Dependencies

​Docker Development Environment

​Performance Considerations

​ResourceLoader Modules

​CDN and Caching

​Progressive Web App

​Checking Your Environment

​Next Steps

Install Citizen

View Demo

Build docs developers (and LLMs) love

Requirements

MediaWiki Version

Why MediaWiki 1.43.0?

Legacy Versions

Installing Legacy Versions

PHP Requirements

PHP Extensions

Server Requirements

Web Server

Database

Client Requirements (Browser Support)

Supported Browsers

Browser Features Required

Browser Compatibility Configuration

Dependencies

PHP Dependencies

JavaScript Dependencies

MediaWiki Core Modules

Codex Components

Vue and Pinia

Optional Enhancements

Recommended Extensions

Styled Extensions

Development Requirements

Node.js and npm

PHP Development Tools

Development Dependencies

Docker Development Environment

Performance Considerations

ResourceLoader Modules

CDN and Caching

Progressive Web App

Checking Your Environment

Next Steps