Configuration

All Finch configuration lives in a FinchConfigs instance that you create once and pass to FinchApp. This page documents every option and its environment variable equivalent.

Project Structure

A typical Finch project looks like this:

.
├── lib/
│   ├── app.dart              # FinchApp setup and main()
│   ├── configs/
│   │   └── setting.dart      # App-level constants (optional)
│   ├── controllers/
│   ├── models/
│   ├── db/
│   ├── route/
│   │   ├── web_route.dart
│   │   └── socket_route.dart
│   ├── languages/            # JSON language files (en.json, fa.json …)
│   └── widgets/              # Jinja template files (*.j2.html)
├── public/                   # Static files served directly
├── migrations/               # MySQL migration SQL files
├── migrations_sqlite/        # SQLite migration SQL files
├── .env
└── pubspec.yaml

FinchConfigs

FinchConfigs is the central configuration class. All constructor parameters have a corresponding .env fallback.

import 'package:finch/finch_app.dart';
import 'package:finch/finch_tools.dart'; // pathTo(), env

FinchConfigs configs = FinchConfigs(
  // --- Server ---
  port: env.getInt('DOMAIN_PORT', 8080),
  ip: '0.0.0.0',
  domain: env.get('DOMAIN', 'localhost'),
  domainScheme: env.get('DOMAIN_SCHEME', 'http'),

  // --- Paths ---
  publicDir: pathTo(env.get('PUBLIC_DIR', './public')),
  widgetsPath: pathTo(env.get('WIDGETS_PATH', './lib/widgets')),
  widgetsType: env.get('WIDGETS_TYPE', 'j2.html'),
  languagePath: pathTo(env.get('LANGUAGE_PATH', './lib/languages')),
  pathCache: pathTo(env.get('PATH_CACHE', './cache_routes')),
  pathMigrationMySQL: './migrations',
  pathMigrationSQLite: './migrations_sqlite',

  // --- Language ---
  languageSource: LanguageSource.json, // or LanguageSource.dart
  // dartLanguages: languageDart,        // used when languageSource == dart

  // --- Databases ---
  dbConfig: FinchDBConfig(
    enable: true,
    host: env.get('MONGODB_CONNECTION', 'localhost'),
    port: env.get('MONGODB_PORT', '27017'),
    user: env.get('MONGODB_USER', 'root'),
    pass: env.get('MONGODB_PASSWORD', 'password'),
    dbName: env.get('MONGODB_NAME', 'my_app'),
    auth: env.get('MONGODB_AUTH', 'admin'),
  ),
  mysqlConfig: FinchMysqlConfig(
    enable: true,
    host: env.get('MYSQL_HOST', 'localhost'),
    port: env.getInt('MYSQL_PORT', 3306),
    user: env.get('MYSQL_USER', 'db_user'),
    pass: env.get('MYSQL_PASS', 'db_password'),
    databaseName: env.get('MYSQL_DATABASE', 'my_db'),
  ),
  sqliteConfig: FinchSqliteConfig(
    enable: true,
    filePath: env.get('SQLITE_PATH', './app.sqlite'),
  ),

  // --- Mail ---
  mailDefault: '[email protected]',
  mailHost: 'smtp.example.com',

  // --- Template engine (Jinja) ---
  blockStart: '{%',
  blockEnd: '%}',
  variableStart: '{{',
  variableEnd: '}}',
  commentStart: '{#',
  commentEnd: '#}',
  // jinjaMapTemplate: mapTemplates, // supply a Map<String,String> to bundle templates

  // --- Security ---
  cookiePassword: env.get('COOKIE_PASSWORD', 'change-me-in-production'),

  // --- Development ---
  enableLocalDebugger: env.getBool('ENABLE_LOCAL_DEBUGGER', false),
);

Key Properties Reference

Property	Type	Default	Purpose
`port`	`int`	`8080`	HTTP server port
`ip`	`String`	`'0.0.0.0'`	Bind address
`domain`	`String`	`'localhost'`	Public domain
`domainScheme`	`String`	`'http'`	`http` or `https`
`domainPort`	`int`	same as `port`	Port used in generated URLs
`publicDir`	`String`	`'public'`	Static file root
`widgetsPath`	`String`	`'bin/widgets'`	Template directory
`widgetsType`	`String`	`'html'`	Template file extension
`languagePath`	`String`	`'languages'`	JSON language file directory
`languageSource`	`LanguageSource`	`.json`	`.json` or `.dart`
`languages`	`List<String>`	keys of the default language map	Whitelist of valid locale codes; requests for a language not in this list fall back to the default. See Localization
`pathCache`	`String`	`'./cache'`	Route response cache directory
`pathMigrationMySQL`	`String`	`'./migrations'`	MySQL migration directory
`pathMigrationSQLite`	`String`	`'./migrations_sqlite'`	SQLite migration directory
`cookiePassword`	`String`	`'password'`	Key for encrypted cookies
`enableLocalDebugger`	`bool`	`false`	Enable debug bar in browser
`fakeDelay`	`int`	`0`	Add artificial response delay (ms)
`poweredBy`	`String`	`'Dart Finch'`	`X-Powered-By` header value
`noStop`	`bool`	`true`	Keep server running after an unhandled error

Database Config Classes

FinchDBConfig (MongoDB)

FinchDBConfig(
  enable: true,
  host: 'localhost',
  port: '27017',       // String
  user: 'root',
  pass: 'password',
  dbName: 'my_app',
  auth: 'admin',       // Auth source database
  maxConnections: 10,  // Size of the mongo_dart connection pool (Db.pool)
)

FinchMysqlConfig

FinchMysqlConfig(
  enable: true,
  host: 'localhost',
  port: 3306,          // int
  user: 'db_user',
  pass: 'db_password',
  databaseName: 'my_db',
  collation: 'utf8mb4_general_ci',
  maxConnections: 10,  // Size of the MySQLConnectionPool
)

FinchSqliteConfig

FinchSqliteConfig(
  enable: true,
  filePath: './app.sqlite',
)

Environment Variables (.env)

Finch reads a .env file in your project root automatically. All FinchConfigs values can be overridden via environment variables. The env map (from finch_tools.dart) exposes both .env and system environment variables.

DOMAIN_PORT=8080
DOMAIN=example.com
DOMAIN_SCHEME=https

MONGODB_CONNECTION=localhost
MONGODB_PORT=27017
MONGODB_USER=root
MONGODB_PASSWORD=secret
MONGODB_NAME=my_app
MONGODB_AUTH=admin

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=db_user
MYSQL_PASS=db_pass
MYSQL_DATABASE=my_db

SQLITE_PATH=./app.sqlite

ENABLE_LOCAL_DEBUGGER=true

isLocalDebug

FinchApp.config.isLocalDebug returns true when the LOCAL_DEBUG environment variable is set to true, or when Dart is running in debug mode (Console.isDebug). Use this flag to enable verbose output or the local debugger bar.

if (FinchApp.config.isLocalDebug) {
  Console.p('Debug mode active');
}

On This Page