SDK 2.0 guide

SDK 2.0 is the offline-first foundation for the Flutter SDK. An app built on it keeps working when the network drops, stores writes locally, and syncs once the phone is back online. The mode is a server switch, not a code fork: the same app binary runs online-only or offline-first depending on what Mobile Configuration says.

Server prerequisites

Install or upgrade Control first. 2.0 needs frappe-mobile-control >= 1.0.0, the version that added the offline_enabled field.

bench get-app https://github.com/dhwani-ris/frappe-mobile-control
bench --site yoursite install-app mobile_control
bench --site yoursite migrate

Already installed:

bench update --apps frappe-mobile-control
bench --site yoursite migrate

Configure the app in the desk

Open Mobile Configuration (System Manager only, one row per site).

Tick Enabled.
Set Package Name and Minimum App Version.
Add the doctypes this app should show under Forms Configuration.
Tick Offline Mode Enabled if this deployment should run offline-first. Leave it off for a thin online client.
Save.

The flag rides on the login response as offline_enabled. Every device picks up the value on its next login.

Step 1

Upgrade Control on the bench

Step 2

Set the flag in Mobile Configuration

Step 3

Ship the app

Rollout order

Server first, flag second, app third. That order matters.

A device that gets the SDK 2.0 build before the server has Control >= 1.0.0 with the flag set reads offline_enabled as false. If that device is holding 1.x offline data, the next launch drains what it can and then drops the local tables. With no connection at that moment the drain fails and the drop still goes ahead, so the data is gone.

There is no way back. sqflite has no downgrade hook and the SDK carries no reverse migration, so a device that moves to the new schema stays on it. Fix forward with patch releases, never downgrade.

No downgrade path

A device that upgrades before the server is ready can lose its offline data permanently. Upgrade Control and set the flag before any device gets the 2.0 build.

The two halves

SDK, on the device

Flutter package. Renders forms from doctype metadata, stores writes in SQLite, syncs when connected.

↔

Control, on the server

Frappe app. Mobile auth, app status, force-update, translations, and the Mobile Configuration switch.

Any app built on the SDK requires Control installed on the Frappe server. They version and release independently.

Versioning

Component	Version
SDK (pub.dev)	`2.0.0-beta.2`
Internal SQLite schema	6
Required server app	`frappe-mobile-control` >= 1.0.0
Downgrade	Not supported

flutter pub add frappe_mobile_sdk still resolves 1.2.0 while 2.0 is in beta. Ask for the beta by name: frappe_mobile_sdk: ^2.0.0-beta.2.

Going deeper

The full detail lives in the SDK repository, under doc/release-2.0/.

What's new: read this when you want every feature with a usage example.
Architecture: read this when you want diagrams of the init flow, read path, and sync engine.
Breaking changes: read this when you're touching SDK call sites and need the full API diff.
Schema migration: read this when you manage the database upgrade path or are debugging a migration.
Migrating from 1.x: read this when you're upgrading an existing 1.x app and want a step-by-step checklist.
Limitations: read this when you hit a wall and want to confirm it's a known gotcha.

Release notes

SDK 2.0.0-beta: the first prerelease, 30 July 2026.
SDK 2.0.0-beta.2: the second prerelease, 12 August 2026. Supersedes beta for new installs.