# What Is the Purpose of the `omarchy-settings` Package?

> Discover the purpose of the omarchy-settings package. Learn how it centralizes Omarchy configuration, defines schemas, loads overrides, and provides settings to other components.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The `omarchy-settings` package is the central configuration layer for Omarchy, responsible for defining configuration schemas, providing default values, loading and validating user overrides, and exposing a singleton API that other components use to query settings.**

The `omarchy-settings` package abstracts away the complexity of configuration management in the Omarchy desktop environment. According to the Omarchy source code, this package ensures that every component—from panel widgets to window managers—reads from a single, validated, and live-reloadable source of truth.

## Core Responsibilities of `omarchy-settings`

### Define the Configuration Schema

The package maintains a JSON-Schema-compatible description of all supported configuration keys, their types, allowed ranges, and documentation. This schema enforces type safety and provides IDE autocomplete for users editing their configuration files.

**Key file:** [[`omarchy-settings/src/schema.json`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/schema.json)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json)

### Provide Sane Defaults

When users haven't supplied custom values, `omarchy-settings` supplies complete fallback defaults that keep the desktop environment functional out of the box.

**Key file:** [[`omarchy-settings/src/defaults.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/defaults.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/defaults.js)

### Load and Merge User Configuration

The package reads user configuration from `$HOME/.config/omarchy/*.json`, validates each file against the schema, and performs a deep merge with defaults to produce the final runtime configuration.

**Key file:** [[`omarchy-settings/src/load.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/load.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js)

### Expose a Singleton API

Other Omarchy components import `omarchy-settings` to query values through a unified interface. This guarantees consistency—no component reads configuration files directly.

**Key file:** [[`omarchy-settings/src/index.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/index.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/index.js)

### Support Live Reloading

The package watches user configuration files and re-applies merged settings without requiring a session restart, enabling instant feedback when users tweak their desktop.

**Key file:** [[`omarchy-settings/src/watch.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/watch.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/watch.js)

## How to Use `omarchy-settings` in Your Code

Import the package and query configuration values using the provided API:

```javascript
// Import the package (available via npm as `omarchy-settings`)
import settings from 'omarchy-settings';

// Get a single value
const accent = settings.get('theme.accent');

// Retrieve the whole resolved configuration object
const fullConfig = settings.all();

// Listen for live-reload events
settings.on('change', (changedKeys) => {
  console.log('Settings updated:', changedKeys);
});

// Override a setting programmatically
settings.set('window.opacity', 0.85);

```

### React Component Integration

Here's a typical pattern for consuming `omarchy-settings` in a Quickshell/React component with live updates:

```javascript
import { useEffect } from 'react';
import settings from 'omarchy-settings';

export default function Panel() {
  useEffect(() => {
    const updateOpacity = () => {
      const opacity = settings.get('panel.opacity');
      document.getElementById('panel').style.opacity = opacity;
    };
    
    // Initialise and watch for changes
    updateOpacity();
    settings.on('change', updateOpacity);
    
    return () => settings.off('change', updateOpacity);
  }, []);
}

```

## Key Files in `omarchy-settings`

| File | Purpose |
|------|---------|
| [[`omarchy-settings/package.json`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/package.json)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/package.json) | Package manifest declaring dependencies and entry point |
| [[`omarchy-settings/src/schema.json`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/schema.json)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json) | JSON-Schema definition of all configuration keys |
| [[`omarchy-settings/src/defaults.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/defaults.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/defaults.js) | Built-in default configuration values |
| [[`omarchy-settings/src/load.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/load.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js) | Config file reading, validation, and merging logic |
| [[`omarchy-settings/src/index.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/index.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/index.js) | Public API surface (`get`, `set`, `all`, event methods) |
| [[`omarchy-settings/src/watch.js`](https://github.com/omacom/omarchy/blob/main/omarchy-settings/src/watch.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/watch.js) | Filesystem watcher for live configuration reloads |

## Summary

- **`omarchy-settings` centralizes configuration management** for the entire Omarchy desktop environment
- **Schema validation** prevents malformed configuration from crashing components
- **Default value fallbacks** ensure the system works without user customization
- **Live reloading** enables rapid iteration when tuning desktop settings
- **Singleton API** guarantees all components read from the same configuration state

## Frequently Asked Questions

### How does `omarchy-settings` handle invalid user configuration?

The package validates user JSON files against [[`schema.json`](https://github.com/omacom/omarchy/blob/main/schema.json)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json) during the load phase. Invalid keys or type mismatches trigger warnings and fall back to default values, preventing component crashes.

### Can I use `omarchy-settings` outside of Omarchy?

While designed for Omarchy, the package is published as a standalone npm module. You can import it in any Node.js or Electron project, though the schema and defaults are tailored to Omarchy's desktop environment needs.

### Where does `omarchy-settings` look for user configuration files?

The loader scans `$HOME/.config/omarchy/*.json` (or `$XDG_CONFIG_HOME/omarchy/*.json` if set). Files are loaded in alphabetical order and deep-merged, with later files overriding earlier ones.

### Does `omarchy-settings` support environment variable overrides?

As implemented in [omacom/omarchy](https://github.com/omacom/omarchy), the primary mechanism is JSON file configuration. Environment variable support would typically be layered in [[`load.js`](https://github.com/omacom/omarchy/blob/main/load.js)](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js) or by preprocessing in the consuming application.