JavaScript Override Scripts
Relevant source files
The following files were used as context for generating this wiki page:
JavaScript Override Scripts allow you to modify the Mihomo configuration dynamically using a JavaScript-based engine. These scripts execute within a secure QuickJS sandbox and interact with the configuration via a main(config) entry point. The system persists these scripts across sessions and applies them according to defined scopes, either globally or to specific subscription profiles.
Sources: apps/desktop/src/ui/plugins.js:5-10, FEATURES.md:65-71
System Architecture
The Override System employs a dual-engine architecture supporting both Prism DSL (YAML) and JavaScript. JavaScript overrides specifically utilize a write_pipeline for live modifications and a test_pipeline for validation. The backend manages script persistence in the prism/overrides/ directory within the application data folder.
Sources: apps/desktop/src-tauri/src/prism/overrides.rs:3-13, apps/desktop/src-tauri/src/prism/overrides_commands.rs:308-316
Execution Flow
When you save or run a script, the system follows a specific pipeline to ensure stability and security.
The execution flow ensures that only valid scripts reach the live configuration, preventing core crashes.
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:308-335, apps/desktop/src/ui/plugins.js:215-235
Security Sandbox and Limits
JavaScript overrides run within a QuickJS sandbox that imposes strict resource limits and permission controls to prevent malicious behavior or accidental resource exhaustion.
Resource Constraints
The system enforces nine distinct resource limits, including:
- Execution Time: 100ms to 300s range.
- Memory: 1MB to 512MB allocation limits.
- Loops/Recursion: Limits on iteration counts (1K–10M) and stack depth (8–512).
Sources: FEATURES.md:65-71, apps/desktop/src/ui/plugins-smart.js:235-255
Permission Controls
Scripts are restricted by four primary permission toggles:
- Network Access: Controls ability to fetch external data.
- Filesystem Access: Restricts file read/write operations.
- Child Process: Prevents execution of system commands.
- Workers: Limits multi-threaded execution.
Sources: apps/desktop/src/ui/plugins-smart.js:205-230, FEATURES.md:65-68
Data Models and Storage
The system tracks overrides through metadata stored in meta.json. Each override is represented as an OverrideItem.
| Field | Type | Description |
|---|---|---|
id | String | Unique UUID for the override. |
name | String | User-defined display name. |
ext | Enum | File extension (js or prism.yaml). |
type | Enum | Source type (local or remote). |
enabled | Boolean | Whether the override is active. |
global | Boolean | If true, applies to all profiles. |
profileIds | Array | Specific subscription profiles this override applies to. |
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:25-35, apps/desktop/src-tauri/src/prism/overrides.rs:5-12
IPC Command API
The frontend communicates with the Rust backend via a suite of Tauri IPC commands.
| Command | Action | Implementation Detail |
|---|---|---|
override_list | GET | Returns all items sorted by their order property. |
override_create | POST | Allocates a new file and initializes with a template. |
override_set_content | PUT | Saves content and optionally performs a dry_run. |
override_apply_all | EXEC | Runs all enabled and scoped scripts in batch. |
override_refresh_remote | SYNC | Re-downloads content for remote type overrides. |
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:24, apps/desktop/src-tauri/src/prism/overrides_commands.rs:301, apps/desktop/src/integration.test.js:80-95
Script Development
A JavaScript override must define a main(config) function. This function receives the current Mihomo configuration object and must return the modified object.
Implementation Example
// Example: Adding a custom rule via JS Override
function main(config) {
log.info('Applying custom routing override');
if (config.rules) {
config.rules.unshift('DOMAIN-SUFFIX,internal.corp,DIRECT');
}
return config;
}
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:188-198, apps/desktop/src/ui/plugins.js:7-9
Error Handling
During execution, the system captures logs and errors. If an error occurs in the script (e.g., a syntax error or runtime exception), the OverrideLog object returns success: false and includes the error message. The UI formats these errors by subtracting the wrapper script preamble (approximately 23 lines) to provide accurate line numbers to the user.
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:301-315, apps/desktop/src/ui/plugins.js:725-745
Batch Pipeline Execution
For performance, multiple overrides are executed using a batch pipeline. This process minimizes expensive disk I/O and core reloads.
Conclusion
JavaScript Override Scripts provide a flexible and powerful way to extend Mihomo's capabilities within Zephyr. By utilizing a batched execution model and a secure sandbox, the system ensures that complex configuration logic can be applied without compromising application stability or security.