Package for extracting values from a config.


  • Built-in validation for error checking:

    • Detects missing mandatory items.
    • Optional scalar values can be assigned default values.
    • Maximum and/or minimum limits can be specified for integer values.
    • Permitted strings can be specified to restrict possible string values.
    • Leading and trailing whitespace in strings removed by default.
    • Multiple whitespace in strings replaced with a single space by default.
    • Empty and blank strings rejected by default.
    • Empty list values are accepted by default. Defaults can be changed.
    • Unexpected items in the config can be detected.
  • Configs can contain logger levels for use with the Dart logging package.

  • Does not use Dart annotations, so programs can be compiled with dart2native.


Example config:

name: "Example"
description: "An example config"

  host: "localhost"
  port: 8080
  tls: true

Program to read the example config:

import 'dart:io';
import 'package:strict_config/strict_config.dart';

class ExampleConfig {
  ExampleConfig(ConfigMap m) {
    name = m.string('name');
    desc = m.stringOptional('description', keepWhitespace: true);
    server = ServerConfig('server'));

  late String name;
  String? desc; // optional
  late ServerConfig server;

class ServerConfig {
  factory ServerConfig(ConfigMap m) {
    final _host = m.string('host');
    final _tls = m.boolean('tls', defaultValue: true);
    final _port =
        m.integer('port', min: 1, max: 65535, defaultValue: _tls ? 443 : 80);

    return ServerConfig._init(_host, _tls, _port);

  ServerConfig._init(, this.tls, this.port);

  String host;
  bool tls;
  int port;

void main(List<String> args) {
  final filename = args.isNotEmpty ? args.first : 'example.conf';

  try {
    final text = File(filename).readAsStringSync();

    final config = ExampleConfig(ConfigMap(text));

    print('Name: ${}');
    if (config.desc != null) {
      print('Description: ${config.desc}');
    print('Host: ${}');
    print('TLS: ${config.server.tls}');
    print('Port: ${config.server.port}');

  } on ConfigException catch (e) {
    stderr.write('Error: $filename: $e\n');
  } on FileSystemException catch (e) {
    stderr.write('Error: ${e.path}: ${e.message}\n');

The above example demonstrates two conventions for dealing with null safety. The ExampleConfig class uses late non-nullable members for mandatory items, and nullable members for optional items. The ServerConfig class uses a factory constructor, so all mandatory members are non-nullable (and don't need to be late).


Create a ConfigMap from the text representation of a config. The text is usually from a config file.

Extract expected values from config maps using the extraction methods.

  • For mandatory scalar values, use boolean, integer and string.
  • For optional scalar values, use booleanOptional, integerOptional and stringOptional.
  • For values which are config maps, use map or mapOptional.
  • For values which are lists use booleans, integers, strings and maps.
  • If the list is optional, use booleansOptional, integersOptional, stringsOptional and mapsOptional.

Use unusedKeysCheck to check a config map for unexpected keys.

See the API reference for details.


Data model

A config is a config map at the top-level.

A config map is an unordered collection of zero or more key-value pairs.

The keys are case-sensitive strings. Within the context of each config map, the keys must be unique.

The values must be one of these types:

  • boolean: true or false
  • integers
  • strings: optionally enclosed in double quotes
  • config maps
  • list of booleans
  • list of integers
  • list of strings
  • list of config maps


A subset of YAML is used as the syntax of a config.

Features and bugs

Please file feature requests and bugs at the issue tracker.


Library for extracting values from a config.