https://github.com/chuckv01/capacitor-localstorage-migration
A Capacitor plugin designed to help migrate legacy web storage data from UIWebView (iOS) and Crosswalk WebView (Android) to modern WebView implementations.
https://github.com/chuckv01/capacitor-localstorage-migration
android capacitor capacitor-plugin ios migration plugin uiwebview wkwebview
Last synced: 4 months ago
JSON representation
A Capacitor plugin designed to help migrate legacy web storage data from UIWebView (iOS) and Crosswalk WebView (Android) to modern WebView implementations.
- Host: GitHub
- URL: https://github.com/chuckv01/capacitor-localstorage-migration
- Owner: Chuckv01
- Created: 2025-03-04T17:10:30.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-07T18:16:46.000Z (over 1 year ago)
- Last Synced: 2025-09-23T03:24:40.337Z (9 months ago)
- Topics: android, capacitor, capacitor-plugin, ios, migration, plugin, uiwebview, wkwebview
- Language: Swift
- Homepage:
- Size: 378 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# 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
```bash
npm install capacitor-localstorage-migration
npx cap sync
```
## Usage
```typescript
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()
```typescript
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
```bash
npm run build
```
### Running Tests
```bash
npm test
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.