# How to Modify Modly's Settings Programmatically: A Complete Guide

> Learn how to modify Modly's settings programmatically using the setSettings function. This guide explains merging partial configurations into your JSON file.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Modly exposes settings manipulation through the `setSettings` function in [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts), which merges partial configuration objects into a JSON file stored in the Electron `userData` directory.**

Modly is an Electron-based application that manages user-configurable paths for models, workspaces, workflows, and dependencies. If you need to modify Modly's settings programmatically, the application provides a type-safe API that isolates file-system operations to the main process while exposing clean interfaces to renderer processes via IPC.

## Where Modly Stores Configuration

Modly persists user settings in a JSON file located within the Electron **userData** directory. This standard Electron location ensures cross-platform compatibility, placing the file in OS-specific application data folders.

The settings file path is constructed by the `settingsPath(userData)` helper function inside [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts). This approach centralizes configuration management, ensuring that all modules—from the Python bridge to the model downloader—read from a single source of truth.

## Core Settings API in settings-store.ts

The heart of Modly's configuration system resides in [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts). This module defines the `AppSettings` interface and provides two primary functions for programmatic access.

### Reading Settings with getSettings

The `getSettings(userData)` function reads the existing configuration from disk or returns sensible defaults if the file does not exist. Other main-process modules like [`python-bridge.ts`](https://github.com/lightningpixel/modly/blob/main/python-bridge.ts) and [`model-downloader.ts`](https://github.com/lightningpixel/modly/blob/main/model-downloader.ts) import this function to read current configuration values.

### Updating Settings with setSettings

The **`setSettings(userData, patch)`** function accepts a partial `AppSettings` object and merges it into the persisted configuration. According to the lightningpixel/modly source code, the implementation performs a shallow merge and writes the result to disk:

```typescript
export function setSettings(userData: string, patch: Partial<AppSettings>): AppSettings {
  const updated = { ...getSettings(userData), ...patch }
  writeFileSync(settingsPath(userData), JSON.stringify(updated, null, 2), 'utf-8')
  return updated
}

```

This function returns the complete updated configuration, allowing you to verify changes immediately after invocation.

## IPC Handler Registration in ipc-handlers.ts

To bridge the gap between the main process and renderer processes, Modly registers IPC handlers in [`electron/main/ipc-handlers.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/ipc-handlers.ts). The **"settings:set"** channel delegates directly to the `setSettings` function:

```typescript
// inside ipc-handlers.ts
ipcMain.handle('settings:set', (event, patch) => {
  const userData = app.getPath('userData')
  return setSettings(userData, patch)
})

```

Similarly, a **"settings:get"** channel (registered elsewhere in the same file) allows renderer processes to retrieve the current configuration without direct file-system access.

## Accessing Settings from Different Contexts

Depending on your execution context—main process, renderer process, or preload script—you can modify Modly's settings using different patterns.

### Main Process (Node.js)

When operating within the Electron main process, import the settings store directly and manipulate configuration using `app.getPath('userData')`:

```typescript
import { app } from 'electron'
import { setSettings, getSettings } from './settings-store'

// Change the models directory at runtime
const userDataPath = app.getPath('userData')
setSettings(userDataPath, { modelsDir: '/custom/models/path' })

// Verify the change
const updated = getSettings(userDataPath)
console.log('New modelsDir →', updated.modelsDir)

```

### Renderer Process via IPC

Renderer processes cannot access the file system directly. Instead, use `ipcRenderer.invoke` to communicate with the main process over the **settings:set** channel:

```typescript
// In a renderer script (e.g., a React component)
import { ipcRenderer } from 'electron'

// Update workspace location
async function changeWorkspace(newPath: string) {
  const result = await ipcRenderer.invoke('settings:set', { workspaceDir: newPath })
  console.log('Settings updated:', result)
}

// Example usage
changeWorkspace('/home/user/my-workspace')

```

### Preload Script Bridge

For secure exposure to the renderer, Modly likely uses a preload script that wraps IPC calls via `contextBridge`:

```typescript
// In preload.ts (exposes a safe API)
contextBridge.exposeInMainWorld('modlyAPI', {
  setSettings: (patch) => ipcRenderer.invoke('settings:set', patch),
  getSettings: () => ipcRenderer.invoke('settings:get')
})

// In the renderer
window.modlyAPI.setSettings({ dependenciesDir: '/opt/deps' })

```

This pattern eliminates direct `ipcRenderer` access in renderer code, adhering to Electron security best practices.

## Summary

- **Configuration Location**: Modly stores settings in `<userData>/settings.json`, accessed via [`electron/main/settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/settings-store.ts).
- **Core Functions**: Use `getSettings(userData)` to read and `setSettings(userData, patch)` to update configuration programmatically.
- **IPC Channels**: Renderer processes interact with settings through `settings:get` and `settings:set` channels defined in [`electron/main/ipc-handlers.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/ipc-handlers.ts).
- **Persistence**: Changes written via `setSettings` immediately persist to disk and are available to all application modules without restart.

## Frequently Asked Questions

### Where does Modly store its configuration file?

Modly stores its configuration in a JSON file within Electron's `userData` directory, typically located at `<userData>/settings.json`. The exact path varies by operating system—Windows uses `%APPDATA%`, macOS uses `~/Library/Application Support/`, and Linux uses `~/.config/`. The [`settings-store.ts`](https://github.com/lightningpixel/modly/blob/main/settings-store.ts) module constructs this path using the `userData` argument passed to its functions.

### How do I update settings from a React component in Modly?

From a React component or any renderer process, invoke the IPC channel `settings:set` using `ipcRenderer.invoke('settings:set', { key: value })`. Pass a partial object containing only the properties you want to change. The function returns a promise that resolves with the complete updated configuration object.

### What is the difference between getSettings and setSettings?

`getSettings(userData)` reads the current configuration from disk and returns the complete `AppSettings` object, while `setSettings(userData, patch)` accepts a partial `AppSettings` object, merges it with existing values, writes the result to disk, and returns the updated configuration. Both functions operate synchronously in the main process.

### Can I modify Modly settings without restarting the application?

Yes. Changes made through `setSettings` take effect immediately and persist across application restarts. Since the function writes directly to the JSON file and returns the updated configuration, other modules that call `getSettings` will receive the new values on their next read cycle without requiring an application restart.