Docs Reference
Config file
Where LumaSync stores its state, what shape the file has, which fields are safe to edit by hand, and how to reset to defaults. Hue credentials live in the OS keychain, not this file.
LumaSync persists all configuration via Tauri’s plugin-store. On disk that lives at:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/com.lumasync.app/app.json |
| Windows | %APPDATA%\com.lumasync.app\app.json |
| Linux | ~/.config/com.lumasync.app/app.json |
The identifier com.lumasync.app is set in src-tauri/tauri.conf.json and is how every OS scopes the app’s per-user state.
Common shorthand on this site is ~/.config/lumasync/app.json — that’s the Linux convention we use in copy, but the real path varies per OS as above.
Shape
The full shape is typed in src/shared/contracts/shell.ts under ShellState. The top-level fields:
| Field | Type | What it stores |
|---|---|---|
schemaVersion | number | Persistence schema version (current: 2); migrations run on bump |
windowWidth / windowHeight | number | null | Last main-window size in pixels |
windowX / windowY | number | null | Last main-window position; v1.5.2 anchors by window centre instead of top-left, with a monitor-clamp guard that snaps the window on-screen if the saved position falls outside the current display geometry |
isCompactMode | boolean | Was the app last used in compact mode? |
activeSectionId | SectionId | Which settings section was last open |
lightingMode | LightingModeConfig | Current mode + per-mode parameters (saturation, smoothing, brightness cap, chip type, firmware profile) |
ledCalibration | LedCalibrationConfig | Edge counts, corner ownership, anchor, direction, gap |
hue.bridge | HueBridgeSummary | null | Paired bridge (IP, ID — not the username/PSK; those live in the OS keychain) |
hue.onboarding.step | HueOnboardingStep | Last reached step in the flow |
hue.credentialStatus | HueCredentialStatus | Valid / needs-repair / unknown |
hue.runtimeTarget | HueRuntimeTarget | Selected Entertainment Area |
roomMap | RoomMapConfig | Room map editor state — objects, zones, positions, layers; schema migrated 1→2 in v1.5.0 to add Hue Zones |
wled.targets | WledTarget[] | Paired WLED boards (IP, LED count, friendly name) |
autoStartOnLogin | boolean | OS login-items enrolment |
updateChannel | 'stable' | 'beta' | Auto-updater channel selector — added v1.5.0 |
updater.checkOnStartup | boolean | Whether to poll GitHub Releases on launch |
Anything not listed above is either computed at runtime (telemetry, stream state) or lives in a sub-config — the LightingModeConfig for example has nested saturation / smoothing / brightness cap fields.
Not in this file: Hue bridge username and PSK, and any future credential-class secret. Those live in the OS keychain (keyring Rust crate → macOS Keychain / Windows Credential Manager / Linux Secret Service) so a back-up of app.json does not leak them, and the file is safe to share when filing a bug report (after redacting the bridge IP if you want to be extra careful).
Safe to edit by hand
Low-risk: windowWidth, windowHeight, isCompactMode, autoStartOnLogin, updater.checkOnStartup, updateChannel. Wrong values just get clamped or ignored.
Moderate-risk: ledCalibration.counts / cornerOwnership / startAnchor / direction. The app re-validates on load, but an unreasonable combo (e.g., zero total LEDs) will render the strip inert until fixed.
High-risk: hue.bridge, hue.credentialStatus, wled.targets. Editing these by hand puts pairing into an inconsistent state — you’re better off clicking Forget bridge / Remove WLED board in Settings and re-pairing.
Do not touch: anything under roomMap unless you know what you’re doing. The coordinate space, zone discriminator, and layer ordering have subtle invariants; the editor maintains them for you.
Format
Plain JSON, written compactly. No comments allowed (JSON standard).
Schema version is tracked explicitly in the schemaVersion field as of the v1.5.0 zone unification. The persistence layer migrates 1 → 2 automatically on first launch (an idempotent, downgrade-safe shim that re-shapes existing room maps for the unified Zone discriminated union); no user action is needed.
Back up the file if you want to preserve a working configuration across machines. Copy to the matching path on the new machine before first launch — and remember the OS keychain entry will need to be re-paired separately, since keychain entries don’t move with the JSON.
Reset to defaults
If the app is stuck (startup crash, UI blank, pairing confused):
- Quit LumaSync (tray → Quit, or kill process).
- Delete
app.json(or rename it toapp.json.bakfor safekeeping). - Relaunch. LumaSync starts with factory defaults: single window, Off mode, no paired Hue bridge, no calibration.
You’ll lose the pairing, calibration, and room map — re-pair and recalibrate from scratch. Takes ~5 minutes.
Related
- First setup — the first time these values get written
- Auto-updater — how updates preserve config
- Telemetry — what the app does and doesn’t transmit