Data Management

​

How localStorage Works

​

What Gets Stored

{
  "2026-03-07": {
    "exercise-1": [
      { "reps": 12, "loggedAt": "2026-03-07T14:30:00.000Z" },
      { "reps": 10, "loggedAt": "2026-03-07T14:35:00.000Z" }
    ],
    "exercise-2": [
      { "reps": 15, "loggedAt": "2026-03-07T14:40:00.000Z" }
    ]
  },
  "2026-03-06": {
    // Previous day's logs
  }
}

"John Doe"

"today"  // active tab
"dark"   // theme preference

​

Storage Implementation

1. Reads value from localStorage
2. Parses JSON string to JavaScript object
3. Returns initial value if key doesn’t exist
4. Returns default value if parsing fails

1. Serializes new value to JSON string
2. Saves to localStorage with setItem()
3. Handles quota exceeded errors gracefully

• Invalid JSON is logged and ignored
• Storage errors are caught and logged
• App continues working with in-memory state

​

Data Retention

​

How Long Data Persists

• You manually clear browser data
• You use the Hard Reset feature
• Browser storage is cleared by the system (rare)
• You uninstall the browser (not just the PWA)

• No automatic cleanup
• No time-based deletion
• Unlimited retention period

​

Browser-Specific Behavior

• localStorage persists across browser restarts
• Survives browser updates
• Only cleared manually or via hard reset

• Similar to Chrome
• May prompt to clear data when disk space is low

• 7-day cap in Private Browsing mode
• Normal mode persists indefinitely
• May clear data on iOS if storage is critically low

​

Cross-Browser Isolation

• Each browser has its own localStorage
• Installing on different browsers = separate data
• Use export/import to sync across browsers

​

Managing Storage Space

​

Checking Storage Usage

1. Open DevTools (F12)
2. Go to Application tab
3. Click Storage in sidebar
4. View usage under “Storage”

1. Application > Local Storage > your domain
2. Click each key to see size
3. completedExercises is usually the largest

​

Storage Limits

• Chrome/Edge: ~10 MB
• Firefox: ~10 MB
• Safari: ~5 MB (may vary)

• 30 days: 10-20 KB
• 1 year: 50-100 KB
• 5 years: 250-500 KB

​

Quota Exceeded Errors

Failed to execute 'setItem' on 'Storage': Setting the value exceeded the quota.

1. Export your data to create a backup
2. Clear old data (see below)
3. Import recent data to continue tracking

​

Clearing Old Data

​

Option 1: Manual Date Removal

1. Export data as backup (Settings > Export Data)
2. Open DevTools (F12) > Application > Local Storage
3. Click completedExercises to view JSON
4. Click to edit the value
5. Remove old date entries (format: YYYY-MM-DD)
6. Save changes

{
  "2025-01-15": { /* old data */ },
  "2025-01-16": { /* old data */ },
  "2026-03-05": { /* recent data */ },
  "2026-03-06": { /* recent data */ }
}

{
  "2026-03-05": { /* recent data */ },
  "2026-03-06": { /* recent data */ }
}

​

Option 2: Export and Filter

1. Export your full data (Settings > Export Data)
2. Open the JSON file in a text editor
3. Edit completedExercises to keep only recent dates
4. Save the modified JSON file
5. Hard reset the app (Settings > Hard Reset)
6. Import the filtered JSON file

​

Option 3: Hard Reset

1. Export data first (cannot be undone without backup!)
2. Go to Settings tab
3. Scroll to “Danger Zone”
4. Click Hard Reset All Data
5. Confirm the action

• All workout logs (completedExercises)
• User name (userName)
• Active tab preference (activeTab)
• Theme resets to default

​

Export & Backup Strategies

​

When to Export

• Weekly exports for active users
• Monthly exports for casual users
• Before major browser updates
• Before clearing browser data
• Before hard reset operations
• Before switching devices

​

Export Process

1. Click Export Data in Settings
2. File downloads as workout-journey-YYYY-MM-DD.json
3. Contains full workout history and settings

{
  "userName": "Your Name",
  "exportDate": "2026-03-07T10:00:00.000Z",
  "completedExercises": {
    // All your workout logs
  },
  "summary": {
    "totalDaysTracked": 45,
    "totalSetsCompleted": 320,
    "currentStreak": 7
  }
}

​

Storing Backups Safely

• Google Drive / Dropbox / OneDrive
• Email to yourself
• Cloud notes (Notion, Evernote)

• USB drive or external hard drive
• Multiple devices for redundancy
• Named with dates for version control

• Keep at least 3 recent exports
• Name files clearly: track-better-2026-03-07.json
• Store in multiple locations
• Test imports periodically to verify backups work

​

Import & Restore Data

​

Import Process

1. Go to Settings tab
2. Click Import Data
3. Select exported JSON file
4. Data is validated and imported
5. Success message appears

• Checks for completedExercises field
• Validates JSON structure
• Imports userName if present
• Shows error for invalid files

​

What Happens on Import

1. Overwrites completedExercises with imported data
2. Merges old and new data (new data wins)
3. Updates userName if present in import
4. Recalculates streak and analytics
5. Updates UI immediately

​

Merging Data from Multiple Devices

1. Export data from Device A
2. Export data from Device B
3. Manually merge JSON files in a text editor:
   • Combine completedExercises date keys
   • Keep most recent userName
   • Merge exercise logs for duplicate dates
4. Import merged file to either device

​

Hard Reset Explained

​

What Hard Reset Does

1. Shows confirmation dialog
2. Clears all React state:
   • setCompletedExercises({})
   • setUserName("")
   • setActiveTab("today")
3. Removes localStorage keys:
   • completedExercises
   • userName
   • activeTab
4. Shows greeting modal for new user setup

​

When to Use Hard Reset

• Starting fresh tracking program
• Clearing test data
• Resolving storage quota issues
• Fixing corrupted data

• Accidentally clicked (cannot undo!)
• Trying to clear one workout (use Reset Today instead)
• Before exporting data

​

Recovery After Hard Reset

1. Do NOT close the browser (data might still be in memory)
2. Check if you have an export file
3. Import the most recent export
4. If no export exists, data is lost

• Export before hard reset
• Read confirmation dialog carefully
• Keep regular backups

​

Recovering Lost Data

​

Scenarios and Solutions

• Import most recent export file
• If no export: data is lost

• Check Downloads folder for old exports
• Check email/cloud for backups
• If none exist: data is lost

• localStorage may still be intact
• Open app and check if data loads
• Export immediately if data is present
• Import to fresh browser profile if needed

• Data is browser-specific
• Go back to old browser
• Export from old browser
• Import to new browser

• Data only on that device
• Recover from exports if you made them
• No server-side backup available

​

Data Cannot Be Recovered If:

• No export file exists
• localStorage was cleared
• Device was factory reset
• Browser was uninstalled
• Hard reset without backup

​

Best Practices

​

Daily Use

• Log workouts as you complete them
• Check streak to stay motivated
• Review history in calendar view

​

Weekly Maintenance

• Export data every Sunday
• Store export in cloud storage
• Verify export file is valid

​

Monthly Review

• Check storage usage in DevTools
• Review old data for cleanup
• Test import process with old export
• Delete very old exports (keep 3 most recent)

​

Before Major Changes

• Export before browser updates
• Export before clearing browser data
• Export before hard reset
• Export before switching devices
• Export before PWA uninstall

​

Advanced Tips

​

Manual localStorage Access

// Read data
const data = JSON.parse(localStorage.getItem('completedExercises'));

// Modify data
data['2026-03-07'] = {}; // Clear a specific date

// Save data
localStorage.setItem('completedExercises', JSON.stringify(data));

​

Automated Backups

javascript:(function(){
  const data = {
    userName: localStorage.getItem('userName'),
    completedExercises: localStorage.getItem('completedExercises')
  };
  const blob = new Blob([JSON.stringify(data)], {type: 'application/json'});
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `backup-${new Date().toISOString()}.json`;
  a.click();
})();

​

Cross-Browser Sync Script

1. Export from multiple browsers
2. Merge JSON files
3. Import to all browsers
4. Keep data in sync

​

Getting Help

1. Check Troubleshooting guide
2. Review FAQ for common questions
3. Open an issue on GitHub
4. Include:
   • Browser and version
   • Error messages
   • Steps to reproduce
   • Export file (if relevant)