Jonathan Miller
114 lines
4.2 KiB
Markdown
114 lines
4.2 KiB
Markdown
[← 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 [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
|
|
|
|
---
|
|
|
|
*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*
|
|
|
|
| Revision | Date | Author | Description |
|
|
|---|---|---|---|
|
|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |
|