flutter_full_restart 1.0.0

flutter_full_restart: ^1.0.0 copied to clipboard

Restart a Flutter app from Dart, on every platform.
Built and maintained by Azerosoft.

flutter_full_restart restarts your app the way a user would by closing and reopening it, or rebuilds just the UI in place. It can wipe app data on the way, which makes logout, account switching and "reset app" flows a single call.

await FullRestart.restart(wipeData: true, keepPreferences: true);

_{UI restart, full restart and data wipe in the example app on iOS and Android.}

Contents #

• Features
• Platform support
• Requirements
• Installation
• Quick start
• Usage
• API overview
• How it works
• Platform setup
• Troubleshooting
• Example app
• Contributing
• About Azerosoft

Features #

• Full restart. Kills the process and cold-starts the app, exactly like closing and reopening it.
• UI restart. Keeps the process and rebuilds the whole widget tree from scratch, for example after a language or theme change.
• Safe data wipe. Deletes the app's files, caches, databases, preferences, keychain items and cookies, with switches to keep preferences or secure storage. Folders shared with the user or other apps are never touched.
• Confirmation dialog. One call that asks the user before restarting.
• Every platform. Android, iOS, macOS, Web (including WebAssembly), Windows and Linux.
• Swift Package Manager ready. iOS and macOS work with Swift Package Manager and CocoaPods, privacy manifest included.
• Never throws. Every call returns true or false, so a failed restart never crashes your app.

Platform support #

On the web, both restart types reload the page, and the data wipe clears browser storage.

Requirements #

Installation #

flutter pub add flutter_full_restart

On iOS, add the URL scheme described in iOS setup. The other platforms need no setup.

Quick start #

Wrap your app in FullRestartScope so a UI restart can rebuild everything:

import 'package:flutter/material.dart';
import 'package:flutter_full_restart/flutter_full_restart.dart';

void main() {
  runApp(const FullRestartScope(child: MyApp()));
}

Then restart from anywhere:

await FullRestart.restart();

Usage #

Full restart #

Kills the process and launches the app again. Use it after installing an update, changing the backend environment or anything else that needs a clean start.

await FullRestart.restart();

UI restart #

Keeps the process and rebuilds the Flutter UI from scratch. Every State below FullRestartScope is disposed and created again.

await FullRestart.restart(type: RestartType.ui);

Restart with a data wipe #

Typical for logout: clear the user's data, keep app-wide settings.

await FullRestart.restart(
  wipeData: true,
  keepPreferences: true,    // keep SharedPreferences / UserDefaults
  keepSecureStorage: false, // clear tokens in the keychain
);

See What wipeData deletes for the exact folders on each platform.

Ask the user first #

final bool restarted = await FullRestart.confirmAndRestart(
  context,
  title: 'Update installed',
  message: 'Restart now to finish updating?',
  confirmLabel: 'Restart',
  cancelLabel: 'Later',
);

Handle UI restarts yourself #

If you would rather not wrap the app in FullRestartScope, register a callback. It runs instead of the automatic rebuild:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  FullRestart.ensureInitialized(onUiRestart: () {
    // For example: reset your state management and go to the first screen.
  });
  runApp(const MyApp());
}

API overview #

Options of restart and confirmAndRestart:

The full API reference is on pub.dev.

How it works #

RestartType.full #

• Android: starts the launcher activity in a new task and exits the process.
• iOS: opens the app's own URL scheme, moves the app to the background and exits.
• macOS: launches a new instance of the app bundle and exits.
• Windows and Linux: start a new instance of the executable with the same arguments and exit.
• Web: reloads the page.

RestartType.ui #

• Android: recreates the Flutter activity, which boots a new Flutter engine, so main() runs again.
• iOS: replaces the root FlutterViewController on the same engine and rebuilds the widget tree via FullRestartScope.
• macOS, Windows and Linux: keep the window and the engine and rebuild the widget tree via FullRestartScope.
• Web: reloads the page.

What wipeData deletes #

IndexedDB on the web is cleared only when neither flag is set.

¹ Android has no keychain. Packages such as flutter_secure_storage keep their data in shared preferences, so they are wiped unless keepPreferences is set. When keepPreferences is set, databases whose name contains keychain are kept.

² Outside the App Sandbox, Documents and the temporary folder belong to the user and to other apps, so only the <bundle id> folders are cleared. The legacy file-based macOS keychain is shared by all apps and never touched. The system may recreate an empty URL cache database in the cache folder right after the wipe; it contains no data.

³ The Windows Credential Manager is shared by every app of the user, so it is never touched. Neither are shared folders such as Documents or %TEMP%. <company>\<product> is the same folder path_provider returns, taken from the executable's version info.

⁴ The Secret Service keyring used by flutter_secure_storage on Linux is shared by every app of the user, so it is never touched. Neither are shared folders such as Documents or /tmp. <app id> is the folder path_provider returns (the GTK application id, or the executable name for older apps), and $XDG_CACHE_HOME / $XDG_DATA_HOME are respected.

Platform setup #

iOS setup #

A full restart reopens the app through a URL scheme equal to its bundle identifier. Add this to ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    </array>
  </dict>
</array>

Without it, a full restart returns false and logs URL_SCHEME_ERROR. UI restarts and data wipes work without it.

Apple discourages apps from quitting on their own. Trigger a full restart only in response to a user action, such as switching language or logging out.

Swift Package Manager #

Nothing to configure. When Swift Package Manager is enabled (the default in recent Flutter versions), Flutter uses the plugin's Package.swift on iOS and macOS. Otherwise it falls back to CocoaPods. Both include a privacy manifest (PrivacyInfo.xcprivacy).

Android #

The Android side is written in Java on purpose: it builds with any Android Gradle Plugin from 7.x to 9.x, with or without the Kotlin Gradle Plugin. No setup is needed.

Troubleshooting #

<key>FlutterDeepLinkingEnabled</key>
<false/>

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
    end
  end
end

Example app #

The example app shows what survives each kind of restart: the Dart session start time, a counter kept in memory and a counter saved to disk. The animations at the top of this page were recorded with it. It runs on all six platforms.

cd example
flutter run

Tested with #

Every push runs analysis, tests and example builds for all platforms on GitHub Actions.

Contributing #

Bug reports, ideas and pull requests are welcome. Please read the contributing guide and our code of conduct first.

• Report a bug
• Request a feature
• Report a security issue (privately, please)

About Azerosoft #

Azerosoft is a design and development studio from Baku, Azerbaijan. We design interfaces and build websites, web and mobile apps, backends, CRM systems and 2D games. We use our packages in our own projects and maintain them for everyone.

• Website: azerosoft.com
• All our packages: pub.dev/publishers/azerosoft.com
• GitHub: github.com/azerosoft
• Email: hello@azerosoft.com

Building something with Flutter? Tell us about your project.

License #

Released under the MIT License.