Mirrors/super-productivity
1
0
Fork 0
mirror of https://github.com/johannesjo/super-productivity.git synced 2026-07-21 02:20:12 +00:00
Code Issues Projects Releases Wiki Activity
super-productivity/docs/wiki/3.06-User-Data.md
Corey Newton 3aa21d751a
docs/wiki content v0.4 (#6257) 
* docs(wiki): enhance keyboard shortcuts documentation

Added detailed descriptions of functional grouping for keyboard shortcuts, including categories such as Global, Navigation, Task management, and UI panels. Updated the Global Shortcuts section for clarity and included platform-specific differences, configurable vs reserved shortcuts, context-dependent behavior, and storage definitions. This improves user understanding of the shortcut system and its configuration.

* docs(wiki): add reference to Web App vs Desktop differences

Updated the 3.00-Reference and 3.02-Settings-and-Preferences documentation to include a new section on differences between the Web app and Desktop app, linking to the newly created [[3.05-Web-App-vs-Desktop]] page. This enhances clarity and provides users with a direct reference for understanding the distinctions.

* docs(wiki): expand short syntax documentation

Enhanced the 3.04-Short-Syntax.md file by detailing the four main short syntax forms for task metadata: tags, projects, time estimates, and due dates. Each syntax form now includes its purpose, grammar, valid and invalid examples, and additional parsing rules. This update improves user understanding of how to effectively utilize short syntax in task management.

* docs(wiki): add User Data reference to documentation

Included a new reference to [[3.06-User-Data]] in both the 3.00-Reference and _Sidebar.md files. This addition enhances navigation and provides users with direct access to information regarding user data management.

* docs(wiki): expand API documentation for Sync Server and Plugin API

Added comprehensive details on the Sync Server REST API and Plugin API, including authentication methods, endpoint descriptions, request/response schemas, error codes, rate limits, and data retention policies. This update significantly enhances the documentation, providing users with a clearer understanding of the APIs available for data synchronization and plugin development.
2026-01-29 17:35:38 +01:00

6.6 KiB
Raw Blame History

User Data

The User Data concept applies only to the desktop (Electron) application. The web app stores data in browser storage (IndexedDB and localStorage) instead. See 3.05-Web-App-vs-Desktop for web vs desktop differences.

Purpose of the User Data Folder

The User Data Folder is the application data directory where the desktop app stores:

  • All user data, settings, and configurations
  • Automatic backups
  • Custom theme file (styles.css)
  • IndexedDB and localStorage data (managed by Electron)

Default Location by Platform

Platform Location
macOS ~/Library/Application Support/superProductivity/
Windows C:\Users\<YOUR_USER_NAME>\AppData\Roaming\superProductivity/ or %APPDATA%\superProductivity
Linux ~/.config/superProductivity/

The path is shown in the UI under Settings → Automatic Backups (without the backups subfolder) and is printed when the app is started from the command line.

Custom Folder Location

You can specify a custom user data directory using the --user-data-dir command-line parameter:

superproductivity --user-data-dir=/path/to/my/data

Trailing slashes are stripped. The custom path is used instead of the default for the session.

Snap Packages (Linux)

For Snap packages on Linux, the app uses the SNAP_USER_COMMON directory so that data is not accessed by the Snap update process. The effective path is $SNAP_USER_COMMON/.config/superProductivity (or the app name equivalent).

Windows Store

The Windows Store build uses a different path that includes the Windows Store package identifier (under Local\Packages\...\LocalCache\Roaming instead of Roaming).

Directory Structure

backups/ subdirectory

  • Stores automatic backup files (JSON).
  • Location: {userData}/backups/.
  • One backup per day; filename format YYYY-MM-DD.json.

styles.css (optional)

  • Custom theme file for desktop styling.
  • Must be created manually by the user and placed directly in the User Data Folder (not in a subfolder).
  • Loaded by the main process and injected into the renderer; invalid CSS may fail to load and is logged.

IndexedDB and localStorage (Electron-managed)

  • IndexedDB databases and localStorage entries live in platform-specific locations under the userData path.
  • Managed by Electron; do not move or edit these files manually.

File Types and Formats

JSON backup files

  • Format: YYYY-MM-DD.json.
  • Content: Complete application state serialized as JSON.
  • Naming: One file per calendar day (e.g. 2025-01-15.json).

CSS theme file

  • File: styles.css (exact name required).
  • Purpose: Custom CSS for theming; user-created and optional.

IndexedDB databases

  • SUP_OPS (current, version 4): Main database. Object stores: ops, state_cache, import_backup, vector_clock, archive_young, archive_old. Holds operations log, state snapshots, vector clocks, and archives.
  • pf: Legacy database used for migration and recovery.
  • SUPPluginCache: Plugin cache.

localStorage keys

UI and app state stored with keys such as:

  • SUP_UI_HELPER, SUP_ACTION_LOG, SUP_LAST_ERROR_ACTION_LOG
  • SUP_IS_PROJECT_LIST_EXPANDED, SUP_IS_TAG_LIST_EXPANDED
  • DARK_MODE, SUP_NAV_SIDEBAR_EXPANDED, SUP_NAV_SIDEBAR_WIDTH, SUP_RIGHT_PANEL_WIDTH
  • SUP_IS_ADD_TO_BOTTOM, and others (see storage-keys.const.ts for the full set).

User-Editable vs System-Managed

User-editable:

  • styles.css — Create and edit for custom themes.
  • Backup files — Can be restored via Settings → Sync & Export → Import/Export → Import from file (see 2.02-Restore-Data-From-Backup).

System-managed (do not edit manually):

  • IndexedDB databases.
  • localStorage entries.
  • Active backup files (readable as JSON but manual editing is not recommended).

Size Limits and Quota

Client-side IndexedDB

  • When QuotaExceededError occurs, the app triggers emergency compaction (24-hour retention instead of 7 days) and uses a circuit breaker to avoid infinite retries.
  • Browser/OS quota and available disk space apply.

SuperSync server (if used)

  • Default quota: 100 MB per user.
  • Automatic cleanup when quota is exceeded.

Permissions

  • The app needs normal read/write access to the User Data Folder. Default locations are under the user's home or app data directory; no administrator/root rights are required.
  • Plugins that need file system access require the nodeExecution permission and explicit user consent.

Recovery and Repair

Automatic data repair

  • Validation runs at several points in the operation lifecycle.
  • Repairs issues such as orphaned tasks, invalid references, and inconsistent relationships; creates REPAIR operations for the log.

Disaster recovery

  • If the main database (SUP_OPS) is missing or corrupted, the app attempts to load from the legacy pf database and run genesis migration.
  • If recovery fails, a full re-sync (or restore from backup) is required.

Backup restoration

  • Restore from a backup file in backups/ via Settings → Sync & Export → Import/Export → Import from file. See 2.02-Restore-Data-From-Backup.

Sync state corrupted

  • When an operation cannot be applied because of missing dependencies, the app throws SyncStateCorruptedError and expects a full re-sync to restore consistent state.

Configuration and Versioning

  • There are no separate config files in the User Data Folder. Configuration is stored in IndexedDB (SUP_OPS, state_cache) and in localStorage (SUP_* and related keys).
  • Database version: SUP_OPS is at schema version 4.
  • Application version: Defined in the build (e.g. src/environments/versions.ts), not stored in the User Data Folder.
  • Backup files: Each JSON file carries full state; naming is by date only.

Application Access (Desktop)

  • Main process: Path obtained via Electron app.getPath('userData'); custom path set with app.setPath('userData', path) when --user-data-dir or Snap logic is used.
  • Renderer: Path is exposed via IPC (e.g. getUserDataPath()).
  • Backups and file sync: Node.js fs APIs (e.g. readFileSync, writeFileSync, readdirSync, statSync, unlinkSync) are used for backup and local file sync.

Notes

  • Web app: Data lives in browser storage only; there is no User Data Folder. See 3.05-Web-App-vs-Desktop.
  • Custom WebDAV syncing: As an alternative to built-in sync, you can sync the contents of the User Data Folder using external WebDAV or cloud sync tools.
  • Themes: Example themes and theme-creation guidance: super-productivity-themes.