Capacitor LocalStorage Migration Plugin

A Capacitor plugin designed to help migrate legacy web storage data from UIWebView (iOS) and Crosswalk WebView (Android) to modern WebView implementations.

When transitioning from older hybrid mobile apps to Capacitor, local storage data can become inaccessible due to WebView changes. This plugin provides a safe way to retrieve that data, ensuring no user information is lost during the upgrade process.

Key features:

• Retrieves localStorage data from legacy WebViews
• Supports both Crosswalk SQLite and System WebView LevelDB formats (Android)
• Preserves original database files for safety
• Supports both iOS (UIWebView) and Android (Crosswalk) platforms
• Enables smooth app transitions without data loss

The plugin maintains the original storage files as a fallback, allowing multiple migration attempts if needed.

Installation

npm install capacitor-localstorage-migration
npx cap sync

Usage

import { LocalStorageMigration } from 'capacitor-localstorage-migration';

async function migrateLocalStorage() {
  try {
    // Check if migration was already completed
    if (localStorage.getItem('migrationCompleted')) {
      console.log('Migration was already completed');
      return true;
    }

    const data = await LocalStorageMigration.getLegacyData();
    
    if (data && Object.keys(data).length > 0) {
      // Do something with the legacy data!
      console.log(data);

      // Example: Copy legacy localStorage to current localStorage
      Object.entries(data).forEach(([key, value]) => {
        localStorage.setItem(key, value);
      });

      // Mark migration as completed
      localStorage.setItem('migrationCompleted', 'true');
      return true;
    } else {
      // If no legacy data found, mark migration completed to avoid future runs
      localStorage.setItem('migrationCompleted', 'true');
      console.log('No legacy data found');
      return false;
    }
  } catch (err) {
    console.error('Error during localStorage migration:', err);
    return false;
  }
}

API

• getLegacyData()

getLegacyData()

getLegacyData() => Promise<{ [key: string]: any; }>

Returns: Promise<{ [key: string]: any; }>

Supported Platforms

• Android
  • Crosswalk SQLite storage (primary)
    • Path: /data/data/[package-name]/app_xwalkcore/Default/Local Storage/file__0.localstorage
    • Handles UTF-16LE encoding
  • System WebView LevelDB storage (fallback)
    • Path: /data/data/[package-name]/app_webview/Default/Local Storage/leveldb/
    • Supports apps that used cordova-plugin-crosswalk-data-migration to move data from Crosswalk to the system WebView
    • Correctly handles LevelDB's append-only format by reading the most recent value for each key
• iOS
  • Retrieves data from UIWebView localStorage
  • Path: [Library]/WebKit/LocalStorage/file__0.localstorage

Android LevelDB Support

If your old Cordova app used cordova-plugin-crosswalk-data-migration, the data may have been moved from the Crosswalk location to the system WebView's LevelDB storage. This plugin automatically checks both locations:

1. First checks for Crosswalk SQLite storage
2. Falls back to system WebView LevelDB storage if Crosswalk storage is not found

The LevelDB reading uses a hidden WebView to reliably access the legacy localStorage:

• Creates a temporary WebView that loads a file:// URL
• This gives access to the legacy localStorage data stored under the file:// origin
• Uses JavaScript to read all localStorage keys and values
• Works across all Android versions and device manufacturers
• 100% reliable since it uses the WebView's own localStorage implementation

Error Handling

The plugin includes comprehensive error handling for common scenarios:

• Database not found
• SQLite reading errors
• Data decoding issues
• Memory constraints

Errors are returned as rejected promises with descriptive messages.

Requirements

• Capacitor 7.0.0 or higher
• iOS 13.0 or higher
• Android API 23 or higher

Development

Building

npm run build

Running Tests

npm test

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.