flutterx_preferences

Persistent and session key-value storage exposed as a synchronous Map<String, String>, with typed accessors for bool, int, double, String, JSON objects and lists. Reads and writes are synchronous: no await after setup.

Installation

flutter pub add flutterx_preferences

Setup

On platforms with files (everything but the web) resolve the data directory once, before runApp:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Preferences.initialize();
  runApp(const MyApp());
}

Without it, opening a persistent storage on those platforms throws a StateError. On the web it is a no-op.

Usage

Storages are plain Map<String, String>:

localStorage['token'] = 'abc';            // default persistent storage
sessionStorage['draft'] = 'hello';        // cleared when the session ends
final cache = loadLocalStorage('cache');  // persistent storage with a name

Preferences wraps any storage with typed accessors:

final prefs = Preferences.local();          // or Preferences.local('cache'), Preferences.session(), Preferences(map)
prefs.setInt('launches', prefs.getInt('launches') + 1);
final theme = prefs.optString('theme');     // null when absent
prefs.setString('theme', null);             // removes the key
  • opt* returns null when the key is absent or its value cannot be decoded.
  • get* returns its fallback in the same cases.
  • set*(key, null) removes the key.

Objects and lists are stored as JSON; you supply the conversion:

prefs.setJson('user', user.toJson());
final user = prefs.optJson('user', fromJson: User.fromJson);

prefs.setList<Tag>('tags', tags, encode: (tag) => tag.name);
final tags = prefs.getList('tags', decode: Tag.parse);

An exception thrown by fromJson or decode propagates. getKeys, containsKey, remove and clear are also available.

Behavior

  • The same name returns the same storage instance, so every Preferences over it sees the same data.
  • Names must match ^[A-Za-z0-9_-]+$, otherwise an ArgumentError is thrown.
  • On IO each storage is the file <name>.local in the application support directory (_local_.local for localStorage), written atomically through a temporary file.
  • A file that cannot be read or is not a JSON object is loaded empty and reported with FlutterError.reportError.
  • On the web localStorage is the raw window.localStorage, without the keys reserved to named storages; writing a key starting with flutterx_preferences: through it throws an ArgumentError. A named storage is one JSON entry under flutterx_preferences:<name>.
  • sessionStorage is the browser sessionStorage on the web and an in-memory map on IO.

Claude Code plugin

The repository ships a plugin with skills that teach Claude Code to integrate the library:

/plugin marketplace add https://gitlab.com/dade.sliep/flutterx_preferences
/plugin install flutterx-preferences@flutterx-preferences

Libraries

flutterx_preferences
Persistent and session key-value storage exposed as a synchronous Map<String, String>.