Hi,
Recently, @picimako spent quite some time investigating a problem with Inconsistent XML persistence with project-level PersistentStateComponent in split mode.
We discussed this internally, and I think it is worth calling out this special case of settings handling in Split Mode more explicitly.
Short version
For project-level PersistentStateComponents in Split Mode, it can make sense to keep the configurable on the backend, even though the general Split Mode guidance usually recommends keeping UI on the frontend.
Why? Because project-level settings are stored on the backend/host (for example in the project’s .idea directory), and the recommended sync direction for project-level settings is InitialFromBackend. If the configurable also runs on the backend, changes are applied first on the side that owns the persisted project state, and then synchronized to the frontend.
Why this is a special case
The general Split Mode guidance is still correct:
- keep UI and latency-sensitive interactions on the frontend
- keep project-local logic and storage on the backend
But project-level persisted settings sit right on that boundary:
- the UI may look like a frontend concern
- the authoritative persisted state is a backend concern
So if a frontend configurable directly edits a project-level persisted service, you are relying on the frontend/backend settings synchronization path to behave exactly as expected. In tricky cases, that can lead to surprising behavior.
Practical recommendation
If you have:
- a project-level
PersistentStateComponent - registered with
<projectSettings .../> - synchronized with
RemoteSettingInfoProvider - and edited from a Settings configurable
then consider this rule of thumb:
If the configurable directly modifies the persisted project state, prefer keeping that configurable on the backend.
This is one of the few cases where putting a configurable on the backend is reasonable.
Related docs
- Split Mode overview:
Split Mode (Remote Development) | IntelliJ Platform Plugin SDK - Persistent State Component in Split Mode:
Persistent State Component in Split Mode | IntelliJ Platform Plugin SDK - Settings guide:
Settings Guide | IntelliJ Platform Plugin SDK
Source references
RemoteSettingInfo.Direction.InitialFromBackend:
intellij-community/platform/platform-impl/src/com/intellij/ide/settings/RemoteSettingInfo.kt at master · JetBrains/intellij-community · GitHubRemoteSettingInfoProvider:
intellij-community/platform/platform-impl/src/com/intellij/ide/settings/RemoteSettingInfoProvider.kt at master · JetBrains/intellij-community · GitHub- example of a project configurable registered on the backend (
git4idea):
intellij-community/plugins/git4idea/backend/resources/intellij.vcs.git.backend.xml at master · JetBrains/intellij-community · GitHub - corresponding configurable implementation:
intellij-community/plugins/git4idea/backend/src/config/GitVcsPanel.kt at master · JetBrains/intellij-community · GitHub - matching remote settings sync metadata:
intellij-community/plugins/git4idea/shared/src/git4idea/config/GitRemoteSettingsInfoProvider.kt at master · JetBrains/intellij-community · GitHub
I hope this helps others avoid the same trap.