Background isolates

Call Restart.restartApp() from the main isolate, where your app can finish saving data and coordinate the UI. A worker should return its result or send a restart request to the main isolate.

One-off work

For a finite task on a native platform, use Isolate.run. This example decodes configuration JSON in a worker, awaits your storage write on the main isolate, and then requests a restart. If decoding or saving fails, it reports the error and does not restart. Call applyConfigurationAndRestart from your app’s UI. Supply the JSON, a function that saves the decoded configuration, and a callback that displays failures:

import 'dart:convert';
import 'dart:isolate';

import 'package:restart_app/restart_app.dart';

Future<void> applyConfigurationAndRestart({
  required String configurationJson,
  required Future<void> Function(Map<String, dynamic>) saveConfiguration,
  required void Function(String message) reportFailure,
}) async {
  try {
    final configuration = await _decodeConfiguration(configurationJson);
    await saveConfiguration(configuration);

    final result = await Restart.restartApp();
    if (!result.success) {
      reportFailure(result.message ?? result.code ?? 'Restart was not accepted.');
    }
  } catch (error) {
    reportFailure('Could not apply the configuration: $error');
  }
}

Future<Map<String, dynamic>> _decodeConfiguration(String source) {
  return Isolate.run(() => jsonDecode(source) as Map<String, dynamic>);
}

The separate _decodeConfiguration function passes only the JSON string to the worker, so it does not capture a widget or either UI callback. Isolate.run closes its communication ports and ends the worker when the computation finishes. Keep platform-plugin calls, including Restart.restartApp(), on the main isolate in this example. The save callback must complete only after the write finishes. If the failure callback updates a widget, check that the widget is still mounted. On iOS, request the restart while the app is active and engine restart is configured.

Existing workers

For a long-lived worker, send a message through a SendPort to a ReceivePort owned by the main isolate. Its listener can await any remaining writes and call Restart.restartApp(). Close the port when its owner is disposed. Initializing BackgroundIsolateBinaryMessenger enables platform-channel access in a worker, but does not coordinate the restart with the UI or other writes. Keep the restart decision on the main isolate.

Start

Guides

Reference

One-off work

Existing workers

​One-off work

​Existing workers

One-off work

Existing workers