Pub Version codecov GitHub Workflow Status GitHub likes popularity pub points


A simple upgrade checker plugin, to e.g. migrate data between app upgrades or to display a change log with new features to your users.


  • Contains a default implementation using the shared preferences of the platform to persist the last known version
  • Minimal effort to check if an app upgrade is given and to update the persisted value
  • Possibility to implement custom getters and setters for the persisted version (e.g. if the last known app version is already available via a database)
  • Helper to easily execute all fitting / relevant upgrades


Getting Started

Add this to your package's pubspec.yaml file:

  on_upgrade: ^1.1.8

More information on


For full examples please see the example app.

Default Implementation

final onUpgrade = OnUpgrade();
final isNewVersion = await onUpgrade.isNewVersion();
if (isNewVersion.state == UpgradeState.upgrade) {
  await onUpgrade.updateLastVersion();

void myDataMigrationOrNewFeatureDialog(String version) {

Execute managed / multiple upgrades

final upgrades = {
  '1.0.0': myDataMigrationOrNewFeatureDialogForVersion1,
  '1.5.0': myDataMigrationOrNewFeatureDialogForVersion15

final onMultipleUpgrade = OnUpgrade();
final isNewVersionMultiple = await onMultipleUpgrade.isNewVersion();
if (isNewVersionMultiple.state == UpgradeState.upgrade) {
  await isNewVersionMultiple.executeUpgrades(upgrades);
  await onMultipleUpgrade.updateLastVersion();

void myDataMigrationOrNewFeatureDialogForVersion1() {

void myDataMigrationOrNewFeatureDialogForVersion15() {

Custom Implementation

Future<String> customVersionGetter() async {
    // Your implementation. Load the last known version.
    // Must return an empty string if no initial version is known (on the first app start, before updateLastVersion() was called the first time).

Future<bool> customVersionSetter([String? version]) async {
    // Your implementation. Update the last known version.
    // Perform the upgrade check before calling this function.

final onUpgradeCustom = OnUpgrade(customVersionUpdate: customVersionSetter, customVersionLookup: customVersionGetter);
final isCustomNewVersion = await onUpgradeCustom.isNewVersion();
if (isCustomNewVersion.state == UpgradeState.upgrade) {
  await onUpgrade.updateLastVersion();

void myDataMigrationOrNewFeatureDialog(String version) {

How to contribute

If you are interested in contributing, please have a look into the contribution guide. Every idea, bug report or line of code is heavily appreciated.


Provides the ability to check if the currently started app is an upgrade.