MokoOnyx/wiki/minification.md

[← Back to Home](Home)

# Minification

MokoOnyx includes an automatic CSS/JS minification system that generates `.min` files at runtime based on the development mode setting.

---

## How It Works

The minification system is implemented in `MokoMinifyHelper` (`helper/minify.php`). It is called from the template's `index.php` on every page load and follows a simple rule:

- **Development mode OFF** (production): `.min` files are generated from source files when the source is newer or the `.min` file is missing
- **Development mode ON**: all `.min` files are **deleted** so the browser loads unminified source files for debugging

---

## Files Managed

### CSS Files

| Source File | Minified Output |
|-------------|----------------|
| `css/template.css` | `css/template.min.css` |
| `css/offline.css` | `css/offline.min.css` |
| `css/editor.css` | `css/editor.min.css` |
| `css/a11y-high-contrast.css` | `css/a11y-high-contrast.min.css` |
| `css/user.css` | `css/user.min.css` |
| `css/theme/light.standard.css` | `css/theme/light.standard.min.css` |
| `css/theme/dark.standard.css` | `css/theme/dark.standard.min.css` |
| `css/theme/light.custom.css` | `css/theme/light.custom.min.css` |
| `css/theme/dark.custom.css` | `css/theme/dark.custom.min.css` |

### JavaScript Files

| Source File | Minified Output |
|-------------|----------------|
| `js/template.js` | `js/template.min.js` |
| `js/gtm.js` | `js/gtm.min.js` |
| `js/user.js` | `js/user.min.js` |

All paths are relative to `media/templates/site/mokoonyx/`.

---

## Staleness Check

The system uses filesystem modification times to determine whether a `.min` file needs regenerating:

1. If the source file does not exist, skip it
2. If the `.min` file exists and its modification time is **newer or equal** to the source, skip it
3. Otherwise, read the source, minify it, and write the `.min` file

This means minification only runs when source files actually change, keeping page load overhead minimal.

---

## CSS Minification

The CSS minifier performs these transformations:

1. Remove CSS comments (preserving IE hacks)
2. Remove whitespace around `{ } : ; , > + ~`
3. Collapse remaining whitespace to single spaces
4. Remove trailing semicolons before closing braces (`;}` becomes `}`)
5. Strip leading/trailing whitespace

---

## JavaScript Minification

The JS minifier performs these transformations:

1. Remove multi-line comments (`/* ... */`)
2. Remove single-line comments (`//`) while preserving URLs
3. Collapse whitespace
4. Remove spaces around operators and punctuation
5. Restore necessary spaces after keywords (`var`, `let`, `const`, `return`, `typeof`, `instanceof`, `new`, `delete`, `throw`, `case`, `in`, `of`)

---

## Build-Time vs Runtime

| Context | What Happens |
|---------|-------------|
| **Runtime** (page load) | `MokoMinifyHelper::sync()` runs on every page load. In production mode, it checks timestamps and regenerates stale `.min` files. The overhead is negligible (filesystem stat calls only when files have not changed). |
| **Build-time** (`make build`) | The Makefile runs `make minify` before packaging. This uses the moko-platform `minify.js` script (Node.js) with `terser` and `clean-css` for higher-quality minification. |
| **Install/Update** | The installer script (`script.php`) deletes all `.min.css` and `.min.js` files in the `css/` and `js/` directories so they are cleanly regenerated by the runtime minifier on the first page load. Vendor `.min` files in `vendor/` are not touched. |

---

## Debug Mode Behaviour

To debug CSS or JS issues:

1. Go to **System → Site Templates → MokoOnyx**
2. Open the **Advanced** tab
3. Set **Development Mode** to **Yes**
4. Save

This immediately deletes all `.min` files. The template will load the unminified source files, making browser DevTools inspection straightforward. Remember to turn development mode **off** for production.

---

*Built with [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) -- Moko Consulting*

---

*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |