typed_config

Manage and persist your application configs (or settings, or preferences, or whatever you wanna call it) with first-class support for many built-in types and custom objects. Saved to disk as JSON.

Supported Types

Type How to Define
String, bool, int, double builder.define('volume', 0.8)
Enum builder.defineEnum('theme', ThemeMode.system, values: ThemeMode.values)
List<T> builder.defineList('tags', ['home', 'work'])
Map<K, V> builder.defineMap('shortcuts', {'save': 'Ctrl+S'})
Custom Objects (DateTime, classes) builder.define('user', user, fromJson: ..., toJson: ...)

Features

  • Type-Safe: Compile-time validation prevents type mismatches and eliminates manual casting.
  • Synchronous Reads: In-memory cache allows instant synchronous reads.
  • Debounced Saves: Non-blocking, debounced file writes prevent disk thrashing during rapid state updates.
  • Domain Groups & Auto-Namespacing: Organize configs into sub-groups (e.g., AudioConfig, UiConfig) that automatically serialize into clean, nested JSON on disk {"audio": {"volume": 0.8}}.
  • Schema Migrations: Safely migrate configuration schemas sequentially between app releases (v1 → v2).
  • Reactive Streams: Listen to real-time updates on any individual config via entry.changes.
  • Live File Watching: Automatically reload changes when the config file is edited externally (e.g. by users in text editors or external tools) without restarting the app.
  • Zero Framework Coupling: Pure Dart library with no Flutter or UI dependencies.


Usage

1. Define your config

Create your configurations schema by extending TypedConfig. You can define individual configs or organize them into groups using builder.group():

enum ThemeMode { system, light, dark }

// Uses Dart 3.13+ Primary Constructors (see below for Dart 3.2 – 3.12 syntax).

// Main application configuration
final class AppConfig(super.builder) extends TypedConfig {
  final language = builder.define('language', 'en');
  final autoCheckUpdates = builder.define('autoCheckUpdates', true);
  final recentProjects = builder.defineList<String>('recentProjects', const []);
  final shortcuts = builder.defineMap<String, String>('shortcuts', {'save': 'Ctrl+S'});

  // If you want to organize your config into groups
  final ui = builder.group('ui', UiConfig.new);
}

// Grouped config
final class UiConfig(super.builder) extends TypedConfig {
  final themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values);
  final compactMode = builder.define('compactMode', false);
  final fontScale = builder.define('fontScale', 1.0);
}

Tip: builder.group('ui', UiConfig.new) namespaces all child entries under "ui", nesting them into structured JSON on disk ({"ui": {"themeMode": ...}}) and can be accessed with appConfig.ui.themeMode.

Using Dart 3.2 – 3.12 (without Primary Constructors)?

In Dart versions prior to 3.13, because standard field initializers cannot reference builder before construction, use Constructor Initialization:

// Main application config
final class AppConfig extends TypedConfig {
  final ConfigEntry<String> language;
  final ConfigEntry<bool> autoCheckUpdates;
  final ConfigEntry<List<String>> recentProjects;
  final ConfigEntry<Map<String, String>> shortcuts;
  final UiConfig ui;

  AppConfig(super.builder)
      : language = builder.define('language', 'en'),
        autoCheckUpdates = builder.define('autoCheckUpdates', true),
        recentProjects = builder.defineList('recentProjects', const []),
        shortcuts = builder.defineMap('shortcuts', {'save': 'Ctrl+S'}),
        ui = builder.group('ui', UiConfig.new);
}

// Grouped config
final class UiConfig extends TypedConfig {
  final ConfigEntry<ThemeMode> themeMode;
  final ConfigEntry<bool> compactMode;
  final ConfigEntry<double> fontScale;

  UiConfig(super.builder)
      : themeMode = builder.defineEnum('themeMode', ThemeMode.system, values: ThemeMode.values),
        compactMode = builder.define('compactMode', false),
        fontScale = builder.define('fontScale', 1.0);
}

Warning

Avoid late final: If you intend to save all of the default values to disk (saveDefaultValue: true), do not declare entries with late final. Because Dart evaluates late fields lazily upon first access, entries cannot register their default values at startup.

2. Initialize once in main()

Load your configuration file asynchronously once at app startup via constructor tear-off (AppConfig.new). After this call, all reads anywhere in your app are 100% synchronous:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final supportDir = await getApplicationSupportDirectory();
  final configFile = File('${supportDir.path}/config.json');

  final appConfig = await TypedConfig.initialize(
    configFile: configFile,
    watchConfigFile: false,
    create: AppConfig.new,
    saveDefaultValue: false,
    schemaVersion: 1,
  );

  runApp(MyApp());
}

3. Read and write configs

// Synchronous read (no await, no FutureBuilder, no spinners)
final currentThemeMode = appConfig.ui.themeMode.value;

// Update (immediate in memory, debounced in disk save)
appConfig.ui.themeMode.value = ThemeMode.dark;

// Check if customized (useful for showing a "Reset" button via !entry.isDefault)
print(appConfig.ui.themeMode.isDefault); // false

// Reset back to default
appConfig.ui.themeMode.reset();
print(appConfig.ui.themeMode.isDefault); // true

// Reset all configs to defaults (preserves schemaVersion)
await appConfig.resetAll();

// Listen to changes for a specific appConfig
appConfig.ui.themeMode.changes.listen((newTheme) {
  print('Theme changed: $newTheme');
});

4. Unit Testing (In-Memory)

Instantiate your configuration in tests without file I/O or temporary directories:

void main() {
  test('theme update test', () {
    final appConfig = TypedConfig.inMemory(create: AppConfig.new);

    expect(appConfig.ui.themeMode.value, ThemeMode.system);
    appConfig.ui.themeMode.value = ThemeMode.dark;
    expect(appConfig.ui.themeMode.value, ThemeMode.dark);
  });
}

5. Schema Migrations

Rule of Thumb:

  • Adding a new setting? You do not need a migration or version bump. Absent keys automatically return their defaultValue.
  • Changing a default value in code?
    • With (saveDefaultValue: false): No migration needed! Users who never modified the setting automatically inherit the new default from code.
    • With (saveDefaultValue: true): If you want existing users to adopt the new default, increment schemaVersion and update the old value in a migration (since the old default was written to their disk file).
  • Renaming, restructuring, or converting types? Increment schemaVersion and supply sequential ConfigMigrator handlers (v1 → v2 → v3):
final appConfig = await TypedConfig.initialize(
  configFile: configFile,
  create: AppConfig.new,
  schemaVersion: 2,
  migrations: {
    2: (m) {
      // Move old key to a new prefix group
      m.rename(['theme'], ['ui', 'themeMode']);

      // Transform existing values or types (e.g. 0..100 to 0.0..1.0)
      m.transform(['audio', 'volume'], (v) => (v as num) / 100.0);

      // Purge a retired feature key
      m.remove(['legacy_telemetry']);
    },
  },
);

Integrations

Because typed_config is pure Dart, you can easily bridge it to Flutter or your favorite state management solution.

Vanilla Flutter

View vanilla flutter setup

Uses InheritedWidget for widget tree access and StreamBuilder for reactive widget rebuilds.

1. Create an AppConfigScope Widget

import 'package:flutter/widgets.dart';

class AppConfigScope extends InheritedWidget {
  final AppConfig appConfig;

  const AppConfigScope({
    super.key,
    required this.appConfig,
    required super.child,
  });

  static AppConfig of(BuildContext context) {
    final scope = context.dependOnInheritedWidgetOfExactType<AppConfigScope>();
    assert(scope != null, 'No AppConfigScope found in context');
    return scope!.appConfig;
  }

  @override
  bool updateShouldNotify(AppConfigScope oldWidget) => appConfig != oldWidget.appConfig;
}

2. Setup in main.dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final supportDir = await getApplicationSupportDirectory();
  final appConfig = await TypedConfig.initialize(
    configFile: File('${supportDir.path}/config.json'),
    create: AppConfig.new,
  );

  runApp(
    AppConfigScope(
      appConfig: appConfig,
      child: const MyApp(),
    ),
  );
}

3. Usage in Widgets

Use StreamBuilder with entry.changes and initialData: entry.value to rebuild only the widgets that depend on this specific config:

class ThemeSelector extends StatelessWidget {
  const ThemeSelector({super.key});

  @override
  Widget build(BuildContext context) {
    final appConfig = AppConfigScope.of(context);

    return StreamBuilder<ThemeMode>(
      stream: appConfig.ui.themeMode.changes,
      initialData: appConfig.ui.themeMode.value,
      builder: (context, snapshot) {
        final themeMode = snapshot.requireData;

        return SegmentedButton<ThemeMode>(
          segments: const [
            ButtonSegment(value: ThemeMode.system, label: Text('System')),
            ButtonSegment(value: ThemeMode.light, label: Text('Light')),
            ButtonSegment(value: ThemeMode.dark, label: Text('Dark')),
          ],
          selected: {themeMode},
          onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
        );
      },
    );
  }
}

Provider

View provider setup

Exposes AppConfig to the widget tree and pairs with StreamBuilder for reactive widget rebuilds

1. Setup in main.dart

import 'dart:io';
import 'package:material_ui/material_ui.dart';
import 'package:provider/provider.dart';
import 'package:typed_config/typed_config.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final appConfig = await TypedConfig.initialize(
    configFile: File('path/to/config.json'),
    create: AppConfig.new,
  );

  runApp(
    Provider<AppConfig>(
      create: (_) => appConfig,
      dispose: (_, appConfig) => appConfig.dispose(),
      child: const MyApp(),
    ),
  );
}

2. Usage in Widgets

class ThemeSelector extends StatelessWidget {
  const ThemeSelector({super.key});

  @override
  Widget build(BuildContext context) {
    final appConfig = context.watch<AppConfig>();

    return StreamBuilder<ThemeMode>(
      stream: appConfig.ui.themeMode.changes,
      initialData: appConfig.ui.themeMode.value,
      builder: (context, snapshot) {
        final themeMode = snapshot.requireData;

        return SegmentedButton<ThemeMode>(
          segments: const [
            ButtonSegment(value: ThemeMode.system, label: Text('System')),
            ButtonSegment(value: ThemeMode.light, label: Text('Light')),
            ButtonSegment(value: ThemeMode.dark, label: Text('Dark')),
          ],
          selected: {themeMode},
          onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
        );
      },
    );
  }
}

Riverpod

View riverpod setup

Exposes AppConfig through ProviderScope and uses an entry.provider extension for reactive widget rebuilds.

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:typed_config/typed_config.dart';

final _entryProviderCache = Expando<Object>();

/// Extension to add a reactive [provider] getter to [ConfigEntry].
extension ConfigEntryRiverpodX<T> on ConfigEntry<T> {
  Provider<T> get provider {
    final cached = _entryProviderCache[this];
    if (cached != null) return cached as Provider<T>;

    final created = Provider<T>((ref) {
      final sub = changes.listen((_) => ref.invalidateSelf());
      ref.onDispose(sub.cancel);
      return value;
    });
    _entryProviderCache[this] = created;
    return created;
  }
}

/// Provider for your main configuration class. Override this in [ProviderScope].
final appConfigProvider = Provider<AppConfig>((ref) {
  throw UnimplementedError('appConfigProvider must be overridden in ProviderScope');
});

Setup in main.dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final appConfig = await TypedConfig.initialize(
    configFile: File('path/to/config.json'),
    create: AppConfig.new,
  );

  runApp(
    ProviderScope(
      overrides: [
        appConfigProvider.overrideWith((ref) {
          ref.onDispose(appConfig.dispose);
          return appConfig;
        }),
      ],
      child: const MyApp(),
    ),
  );
}

Usage in Widgets

class ThemeSelector extends ConsumerWidget {
  const ThemeSelector({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final appConfig = ref.watch(appConfigProvider);

    // Notice the usage of .provider here
    final themeMode = ref.watch(appConfig.ui.themeMode.provider);

    return SegmentedButton<ThemeMode>(
      segments: const [
        ButtonSegment(value: ThemeMode.system, label: Text('System')),
        ButtonSegment(value: ThemeMode.light, label: Text('Light')),
        ButtonSegment(value: ThemeMode.dark, label: Text('Dark')),
      ],
      selected: {themeMode},
      onSelectionChanged: (selected) => appConfig.ui.themeMode.value = selected.first,
    );
  }
}

Additional information

  • Issues & Feedback: File bug reports and feature requests on GitHub Issues.

Libraries

typed_config
A type-safe key-value store for application configurations with synchronous in-memory reads and disk persistence.