Build System and Asset Processing

Relevant source files

• .gitignore
• assets/css-flags/flags.php
• assets/flags/flags.php
• bin/flags-png.php
• bin/flags-svg.php
• package-lock.json
• package.json

Purpose and Scope

This document describes the build system used to process and bundle frontend assets for the Multisite Language Switcher plugin. It covers the npm-based build pipeline that transforms source JavaScript, LESS stylesheets, and Gutenberg block code into production-ready assets. The build system handles three primary asset types: minified JavaScript for the admin interface, compiled and minified CSS, and bundled Gutenberg block code.

For information about testing infrastructure, see Testing Framework. For CI/CD workflows that invoke these build steps, see CI/CD and Deployment.

---

Build Tools and Dependencies

The build system relies on npm packages defined in package.json1-22 The plugin uses a minimal set of production dependencies for asset processing, with additional development dependencies for testing:

Production Dependencies

Package	Version	Purpose
uglify-js	^3.19.3	JavaScript minification
less	^4.4.2	LESS stylesheet compilation
less-plugin-clean-css	^1.6.0	CSS minification via clean-css

Development Dependencies

Package	Version	Purpose
@wordpress/scripts	^31.1.0	Gutenberg block bundling via webpack
@playwright/test	^1.57.0	End-to-end testing
@wordpress/e2e-test-utils	^11.34.0	WordPress E2E test utilities

Sources: package.json9-20

---

Asset Processing Pipeline

The build system transforms source files into production-ready assets that are excluded from version control. Built assets are listed in .gitignore9-10 to prevent committing generated files.

Build Pipeline: Source to Distribution

Sources: package.json2-8 .gitignore9-10

---

NPM Scripts

Build tasks are defined as npm scripts in package.json2-8 Each script handles a specific asset type:

Individual Build Scripts

Script	Command	Purpose
uglify	uglifyjs src/msls.js > assets/js/msls.js	Minify admin JavaScript
less	lessc assets/css/msls.less assets/css/msls.css --clean-css="--s1 --advanced"	Compile and minify LESS to CSS
build-msls-block	wp-scripts build --webpack-src-dir=src/msls-widget-block --output-path=assets/js/msls-widget-block	Bundle Gutenberg block

Composite Build Script

The build script executes all asset processing steps sequentially:

This composite script is invoked by CI/CD workflows during plugin deployment. See CI/CD and Deployment for details on automated builds.

Sources: package.json2-8

---

JavaScript Minification

The uglify script processes a single JavaScript source file using UglifyJS:

Input: src/msls.js (source code, version-controlled)
Output: assets/js/msls.js (minified, git-ignored)
Tool: uglifyjs version ^3.19.3

The minification process:

1. Removes whitespace and comments
2. Shortens variable names where possible
3. Performs basic optimizations
4. Outputs to assets/js/msls.js via shell redirection

This JavaScript file is enqueued in the WordPress admin interface to provide autocomplete functionality in the translation linking meta boxes (see Post and Page Meta Boxes).

Sources: package.json3 package.json12

---

CSS Compilation and Minification

The less script compiles LESS stylesheets to CSS with integrated minification:

Input: assets/css/msls.less (LESS source, version-controlled)
Output: assets/css/msls.css (compiled and minified CSS, git-ignored)
Tools: less ^4.4.2 + less-plugin-clean-css ^1.6.0

The compilation pipeline:

1. LESS Compilation: lessc processes variables, mixins, and nested rules
2. CSS Minification: clean-css plugin applies aggressive minification
   • --s1: Level 1 optimizations (safe transformations)
   • --advanced: Additional advanced optimizations

The resulting CSS file styles admin interface elements including meta boxes, custom columns, and the language switcher widget.

Sources: package.json4 package.json10-11

---

Gutenberg Block Building

The build-msls-block script bundles the language switcher Gutenberg block using WordPress's official build tools:

Input: src/msls-widget-block/ directory (React/JSX source)
Output: assets/js/msls-widget-block/ directory (bundled JS, git-ignored)
Tool: @wordpress/scripts version ^31.1.0

The @wordpress/scripts package provides a webpack-based build system configured for WordPress block development. It handles:

• JSX Transformation: Compiles React JSX syntax to JavaScript
• Module Bundling: Resolves imports and creates optimized bundles
• Asset Generation: Creates asset manifests for WordPress enqueuing
• Dependency Extraction: Generates dependency lists for proper script loading

The webpack configuration is managed by @wordpress/scripts and includes:

• Babel transpilation for modern JavaScript
• Minification and code splitting
• Source map generation for development

The built block is registered in WordPress and renders the language switcher in the block editor. See Widgets and Gutenberg Blocks for usage details.

Sources: package.json5 package.json18

---

Flag Icon Mapping Generation

The build system includes utility scripts that generate PHP configuration files mapping language codes to flag icons. These are not part of the standard npm run build workflow but are run manually when WordPress adds new translation teams.

Flag Mapping Scripts

PNG Flag Mapping

The bin/flags-png.php1-137 script:

1. Reads WordPress translation data from build/translations.json
2. Scans available PNG flag icons in assets/flags/
3. Maps language codes to flag filenames using built-in exceptions table
4. Generates assets/flags/flags.php1-157 with a PHP array mapping

SVG Flag Mapping

The bin/flags-svg.php1-137 script follows the same pattern but:

• Scans SVG flags in assets/css-flags/flags/4x3/
• Generates CSS class names like flag-icon-de instead of filenames
• Outputs to assets/css-flags/flags.php1-157

Exception Handling

Both scripts contain exception tables (bin/flags-png.php34-86 bin/flags-svg.php33-84) that manually map languages to flags when the automatic mapping fails:

Unused Icon Reporting

Both scripts report unused flag icons at the bottom of generated files (assets/flags/flags.php141-156 assets/css-flags/flags.php141-156), helping maintainers identify which flag assets could be removed to reduce package size.

Sources: bin/flags-png.php1-137 bin/flags-svg.php1-137 assets/flags/flags.php1-157 assets/css-flags/flags.php1-157

---

Build Workflow Integration

The build system integrates with the plugin's development and deployment workflows:

Complete Build Workflow

Development Workflow

Developers work with source files and run npm run build locally to generate assets for testing. Built assets in assets/js/ are excluded from version control via .gitignore9-10

CI/CD Integration

The deployment workflow (see CI/CD and Deployment) rebuilds all assets in a clean environment:

1. GitHub Actions checks out the repository
2. composer run-script build installs npm dependencies
3. npm run build generates fresh assets
4. WordPress Plugin Check validates the complete package
5. Built assets are included in the SVN deployment to WordPress.org

This ensures that distributed plugin packages always contain properly built assets, even though they're not committed to git.

Sources: package.json2-8 .gitignore9-10

---

Asset Distribution

Built assets are included in the distributed plugin but excluded from the git repository:

Git-Tracked Files

• src/msls.js - JavaScript source
• assets/css/msls.less - LESS source
• src/msls-widget-block/ - Gutenberg block source
• package.json - Build configuration
• package-lock.json - Dependency lock file

Git-Ignored (Build Artifacts)

• assets/js/msls.js - Minified JavaScript
• assets/js/msls-widget-block/ - Bundled Gutenberg block
• node_modules/ - npm dependencies

WordPress.org Distribution

The .distignore file (see WordPress.org Integration) controls which files are excluded from the WordPress.org SVN repository. Built assets are included in the distribution package, while development tools (node_modules/, tests/, etc.) are excluded.

Sources: .gitignore9-10 package.json1-22