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['DOMAIN_PORT'] ?? '8080').toInt(def: 8080),
  ip: '0.0.0.0',
  domain: env['DOMAIN'] ?? 'localhost',
  domainScheme: env['DOMAIN_SCHEME'] ?? 'http',

  // --- Paths ---
  publicDir: pathTo(env['PUBLIC_DIR'] ?? './public'),
  widgetsPath: pathTo(env['WIDGETS_PATH'] ?? './lib/widgets'),
  widgetsType: env['WIDGETS_TYPE'] ?? 'j2.html',
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? './lib/languages'),
  pathCache: pathTo(env['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['MONGODB_CONNECTION'] ?? 'localhost',
    port: env['MONGODB_PORT'] ?? '27017',
    user: env['MONGODB_USER'] ?? 'root',
    pass: env['MONGODB_PASSWORD'] ?? 'password',
    dbName: env['MONGODB_NAME'] ?? 'my_app',
    auth: env['MONGODB_AUTH'] ?? 'admin',
  ),
  mysqlConfig: FinchMysqlConfig(
    enable: true,
    host: env['MYSQL_HOST'] ?? 'localhost',
    port: (env['MYSQL_PORT'] ?? '3306').toInt(def: 3306),
    user: env['MYSQL_USER'] ?? 'db_user',
    pass: env['MYSQL_PASS'] ?? 'db_password',
    databaseName: env['MYSQL_DATABASE'] ?? 'my_db',
  ),
  sqliteConfig: FinchSqliteConfig(
    enable: true,
    filePath: env['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['COOKIE_PASSWORD'] ?? 'change-me-in-production',

  // --- Development ---
  enableLocalDebugger: (env['ENABLE_LOCAL_DEBUGGER'] ?? false).toString().toBool,
);

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`
`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
)

FinchMysqlConfig

FinchMysqlConfig(
  enable: true,
  host: 'localhost',
  port: 3306,          // int
  user: 'db_user',
  pass: 'db_password',
  databaseName: 'my_db',
  collation: 'utf8mb4_general_ci',
)

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