Preferences Generator #

A powerful, type-safe code generation solution for creating preference and settings classes in Dart & Flutter.

This package provides a clean, annotation-based API to eliminate boilerplate code for managing user settings, allowing you to interact with shared_preferences, flutter_secure_storage, or any other key-value store in a fully type-safe manner.

Features #

• ✅ Type-Safe: No more magic strings. Get compile-time safety for all your preference keys and types.
• 🧱 Storage Agnostic: Use any key-value store by implementing a simple PreferenceAdapter.
• ⚙️ Boilerplate Reduction: Define your preferences once in an abstract class and let the generator do the rest.
• 🎯 Rich Type Support: Out-of-the-box support for int, String, double, bool, DateTime, Duration, List, Set, Map, Enum, and Record.
• 🚀 Developer Friendly: Fails at build-time with clear, helpful errors for misconfigurations.

Getting Started #

Follow these steps to integrate the Preferences Suite into your project.

1. Installation #

Add the necessary dependencies to your pubspec.yaml file. You will need preferences_annotation as a regular dependency, and this package (preferences_generator) along with build_runner as dev dependencies.

pubspec.yaml

dependencies:
  preferences_annotation: ^1.0.1

dev_dependencies:
  preferences_generator: ^1.1.0
  build_runner: ^2.4.11

2. Create Your Preference Module #

Create an abstract class annotated with @PreferenceModule. This class defines a group of related settings.

lib/settings.dart

import 'package:preferences_annotation/preferences_annotation.dart';
import 'in_memory_adapter.dart'; // We will create this in the next step

part 'settings.g.dart';

@PreferenceModule()
abstract class AppSettings with _$AppSettings {
  factory AppSettings(PreferenceAdapter adapter, {
    // A non-nullable enum with a required default value.
    @PreferenceEntry(defaultValue: AppTheme.system) 
    AppTheme theme,

    // A nullable Duration. No default value is needed.
    @PreferenceEntry() 
    Duration? sessionTimeout,
  }) = _AppSettings;

  // Optional async constructor for preloading preferences.
  static Future<AppSettings> create(PreferenceAdapter adapter) async {
    final instance = _AppSettings(adapter);
    await instance._load();
    return instance;
  }
}

3. Implement a Preference Adapter #

You must provide an implementation of the PreferenceAdapter interface that connects to your storage backend. Here is a lightweight, fully-functional example using a simple in-memory Map. This is great for testing or simple use cases.

lib/im_memory_adapter.dart

import 'dart:convert';
import 'package:preferences_annotation/preferences_annotation.dart';

class InMemoryAdapter implements PreferenceAdapter {
  final Map<String, dynamic> _map = {};

  @override
  Future<void> clear() async => _map.clear();

  @override
  Future<bool> containsKey(String key) async => _map.containsKey(key);

  @override
  Future<void> remove(String key) async => _map.remove(key);

  @override
  Future<T?> get<T>(String key) async {
    final value = _map[key];
    if (value == null) return null;

    // The generator asks for the storable type (e.g., int for Duration).
    // The adapter must convert it back to the rich type.
    if (T == Duration && value is int) {
      return Duration(microseconds: value) as T?;
    }
    // The generator handles Enum/Record deserialization before this call.
    // For other types like List/Set/Map, they are stored as JSON strings.
    if (T == List || T == Set || T == Map) {
      try {
        final decoded = jsonDecode(value as String);
        if (T == Set && decoded is List) return decoded.toSet() as T?;
        return decoded as T?;
      } catch (_) {
        return null;
      }
    }
    // For primitives, the type should match directly.
    if (value is T) return value;

    return null;
  }

  @override
  Future<void> set<T>(String key, T value) async {
    if (value == null) {
      await remove(key);
      return;
    }

    // The generator provides the storable type. The adapter must handle it.
    // For enums (String) and records (Map), they fall into the final else block.
    if (value is int || value is double || value is bool || value is String) {
      _map[key] = value;
    } else if (value is DateTime) {
      // Not a storable type, so we must convert it.
      _map[key] = value.toIso8601String();
    } else if (value is List || value is Set || value is Map) {
      // Convert collections to a JSON string for storage.
      _map[key] = jsonEncode(value);
    } else {
      throw ArgumentError('InMemoryAdapter does not support type ${value.runtimeType}');
    }
  }
}

(For shared_preferences and flutter_secure_storage implementation, see the examples in the project repository.)

4. Run the Code Generator #

Run build_runner in your terminal to generate the settings.g.dart part file.

dart run build_runner build --delete-conflicting-outputs

5. Use Your Preference Module #

Instantiate and use your type-safe AppSettings class.

lib/main.dart

import 'settings.dart';
import 'in_memory_adapter.dart';

Future<void> main() async {
  final adapter = InMemoryAdapter();
  final appSettings = AppSettings.create(adapter);

  // Set a preference
  await appSettings.setTheme(AppTheme.dark);

  // Get a preference
  final theme = appSettings.theme;
  print('Current theme: ${theme.name}');

  // Set nullable value
  await appSettings.setSessionTimeout(Duration(minutes: 15));
  print('Session timeout: ${appSettings.sessionTimeout?.inMinutes} minutes');

  // Remove a preference
  await appSettings.removeSessionTimeout();
  print('Session timeout after removal: ${appSettings.sessionTimeout}');
}

Reactive UI with ChangeNotifier #

To build UIs that automatically react to preference changes, mix in Flutter's ChangeNotifier. The generator detects this and calls notifyListeners() for you.

1. Add the ChangeNotifier Mixin:

   import 'package:flutter/foundation.dart';
      
   @PreferenceModule()
   abstract class AppSettings with _$AppSettings, ChangeNotifier { // Add mixin
      // ... same factory constructor as before
   }
   

2. Listen to Changes in Your UI: Use a ListenableBuilder to efficiently rebuild only the widgets that depend on a specific preference.

   // Get your settings instance (e.g., from a DI container)
   final appSettings = getIt<AppSettings>();
   
   ListenableBuilder(
     listenable: appSettings,
     builder: (context, child) {
       // This Text widget will rebuild whenever any setting changes.
       return Text('Current theme is: ${appSettings.theme.name}');
     },
   )
   

License #

This project is licensed under the MIT License.