# How to Customize vorssaint-utils: A Deep Dive Into Its Modular Architecture

> Customize vorssaint-utils easily using feature toggles runtime settings and custom data blobs without altering core code Unlock full flexibility for your projects.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: deep-dive
- Published: 2026-09-13

---

**vorssaint-utils can be customized through three extensible layers—feature toggles, runtime settings, and custom data blobs—allowing users to enable modules, modify behaviors, and inject custom assets without modifying the core source code.**

vorssaint-utils is built around a highly modular Swift architecture that supports deep customization via UserDefaults and enum-driven configuration. Whether you want to disable unused features, remap shortcuts, or provide custom icons and URL filtering rules, the repository provides explicit extension points in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift) and related settings files. This guide explores the specific mechanisms that allow vorssaint-utils to be customized at runtime.

## Feature-Level Customization via AppFeature

The primary mechanism for controlling which functionality is available lives in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift). Each capability is defined as a case in the `AppFeature` enum, and availability is controlled through dedicated UserDefaults keys.

### Toggling Features at Runtime

Every feature exposes an `availabilityKey` derived from its raw value. When you toggle a feature in the UI, the app writes a boolean to this key, and the system automatically unloads or reloads the corresponding UI components and services without requiring an app restart.

```swift
// Disable the Window Layout feature programmatically
UserDefaults.standard.set(false, forKey: AppFeature.windowLayout.availabilityKey)

```

This logic appears in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) at lines 85-86, where the `availabilityKey` property returns the persistent storage identifier. Because the Settings UI references `AppFeature.allCases` to build the Features hub, adding a new case automatically surfaces it in the interface without migration code.

### Adding New Features to the Catalog

To extend the app with a new module, insert a case into the enum and provide metadata such as group classification, symbols, and required permissions:

```swift
enum AppFeature: String, CaseIterable {
    case windowLayout
    case screenRecorder
    case radialMenu
    case nightMode  // New custom feature
}

```

The `FeatureGroup` logic organizes these into the Settings interface, and the `enabledKeys` array (lines 95-108) determines which specific UserDefaults flags must be true for the system to consider that feature actively engaged.

## Runtime Settings and DefaultsKey

Beyond binary on/off states, vorssaint-utils exposes granular behaviors through the `DefaultsKey` struct. These keys define UserDefaults entries for shortcut preferences, icon assets, and processing rules that take effect immediately.

### Persistent Configuration Storage

Individual options bind directly to SwiftUI's `@AppStorage` or manual wrappers in [`SettingsView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SettingsView.swift). For example, enabling "focus follows mouse" writes to a specific defaults key:

```swift
UserDefaults.standard.set(true, forKey: DefaultsKey.focusFollowsMouseEnabled)

```

According to the source code in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) (lines 95-108), a feature's `enabledKeys` property lists which defaults must evaluate to true for the system to consider that feature active. This allows features to remain dormant until specific sub-options are enabled, preserving user configuration across toggle cycles.

## Custom Data Blobs: Icons, URLs, and Date Patterns

The deepest layer of customization involves storing rich user-defined data as `Data` objects in UserDefaults. This supports custom radial menu icons, URL-cleaning parameters, and date-formatting patterns without rebuilding the app.

### Custom Radial Menu Icons

Users can assign custom images to radial menu items. These images are compressed and stored as `Data` under `DefaultsKey.radialMenuItems`. The `RadialMenuIconStore` handles encoding and decoding as implemented in [`RadialMenuSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/RadialMenuSettings.swift):

```swift
import AppKit

func setCustomIcon(for itemID: UUID, image: NSImage) {
    guard let pngData = image.tiffRepresentation?.compressed(using: .zlib) else { return }
    var items = RadialMenuSupport.decode(UserDefaults.standard.data(forKey: DefaultsKey.radialMenuItems))
    if let index = items.firstIndex(where: { $0.id == itemID }) {
        items[index].customIconData = pngData
        UserDefaults.standard.set(RadialMenuSupport.encode(items), forKey: DefaultsKey.radialMenuItems)
    }
}

```

See [`Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift) (lines 875-1098) for the full implementation of custom icon persistence and `RadialMenuIconStore.customIcon(for:)` retrieval logic.

### URL Cleaner Custom Parameters

The URL cleaning feature allows users to define arbitrary query parameters to strip from copied URLs. These are stored as comma-separated strings and parsed via `URLCleaning.customParameters(from:)` in [`URLCleanerSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/URLCleanerSettings.swift):

```swift
// Define custom tracking parameters to remove
let customNames = "ref,utm_source,session_id"
UserDefaults.standard.set(customNames, forKey: DefaultsKey.urlCleanerCustomNames)

```

The parsing logic resides at lines 271-306, where the function splits the string and applies it to URL processing. This allows users to customize URL hygiene rules without modifying the underlying cleaning engine.

### Custom Date-Time Patterns for Text Snippets

Text snippets support user-defined date formats through [`DateVariableBuilder.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/DateVariableBuilder.swift) (lines 165-170). When users select the "custom" style, the pattern string passes directly to `DateFormatter` via UserDefaults:

```swift
let customPattern = "dd/MM/yyyy HH:mm"
UserDefaults.standard.set(customPattern, forKey: DefaultsKey.textSnippetCustomPattern)

```

This allows arbitrary date formatting without code changes, as the snippet engine reads this key at runtime and applies it to timestamp generation.

## Permission and Onboarding Customization

Each `AppFeature` declares required system permissions via the `permissions` and `onboardingPermissions` properties (lines 50-104 in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift)). This modular permission system means broad permissions like Accessibility or Screen Recording appear in the initial onboarding flow only if required by currently enabled features, while contextual permissions are requested on-demand when specific radial menu shortcuts trigger protected actions.

## Summary

- **vorssaint-utils can be customized** at three distinct levels: feature availability, runtime settings, and rich custom data blobs stored in UserDefaults.
- **Feature toggles** use the `AppFeature` enum in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift), where each case automatically generates a persistent `availabilityKey` that controls module loading.
- **Settings** persist via `DefaultsKey` entries that bind to SwiftUI controls in [`SettingsView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SettingsView.swift), allowing immediate behavior changes without relaunching.
- **Custom data** like radial menu icons, URL cleaning rules, and date patterns are encoded as `Data` objects and decoded by helper structs such as `RadialMenuIconStore` and `URLCleaning`.
- **Extensions** require only adding enum cases or defaults keys; end-users customize via the built-in UI without touching source code.

## Frequently Asked Questions

### Can vorssaint-utils be customized without recompiling the source code?

Yes. End-users can customize vorssaint-utils entirely through the built-in Settings interface. All customizations—including enabling features, setting shortcuts, and adding custom icons or URL rules—persist via UserDefaults and take effect immediately without code changes or recompilation.

### How do I add a completely new feature to vorssaint-utils?

Adding a feature requires modifying [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift) to insert a new case in the `AppFeature` enum, then rebuilding the app. Once added, the feature automatically appears in the Settings UI via `AppFeature.allCases` and maintains its own availability state through the `availabilityKey` property.

### Where are custom radial menu icons stored in vorssaint-utils?

Custom icons are stored as compressed `Data` blobs in UserDefaults under `DefaultsKey.radialMenuItems`. The `RadialMenuIconStore` struct in [`RadialMenuSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/RadialMenuSettings.swift) (lines 875-1098) handles encoding and decoding, allowing user-provided images to persist across app restarts and feature toggles.

### Can I customize which URL parameters vorssaint-utils removes?

Yes. The URL Cleaner feature supports custom parameters through `DefaultsKey.urlCleanerCustomNames`. Users provide a comma-separated list of parameter names, which `URLCleaning.customParameters(from:)` parses in [`URLCleanerSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/URLCleanerSettings.swift) (lines 271-306) and applies to all copied URLs automatically.