typed_config
Manage and persist your application configs (or settings, or preferences, or whatever you wanna call it) with first-class support for built-in types, enums, and custom objects. Saved to disk as JSON.
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);
// 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 accessed viaappConfig.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 UiConfig ui;
AppConfig(super.builder)
: language = builder.define('language', 'en'),
autoCheckUpdates = builder.define('autoCheckUpdates', true),
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, incrementschemaVersionand update the old value in a migration (since the old default was written to their disk file).- Renaming, restructuring, or converting types? Increment
schemaVersionand supply sequentialConfigMigratorhandlers (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.