Finch Configuration in pubspec.yaml

The finch section in pubspec.yaml provides project settings to the Finch CLI. Commands such as finch run, finch serve, finch build, finch migrate --create, and finch make:migration use this section to find entry points, project resources, the build output path, and the directory where migrations are created.

These settings are different from FinchConfigs. The finch section controls the command-line tool, while FinchConfigs holds runtime application settings such as the port, database configuration, and static file directory.

Complete Example

# Finch configuration
# See https://pub.dev/packages/finch for more details
# Here you can customize paths and settings for your Finch application
# They will be used by Finch CLI commands to run, build, serve, migrate, etc.
# Adjust these settings as needed for your project structure
finch:
  # Main path of the application
  app: ./lib/app.dart
  # Path of serve file while developing
  serve: ./lib/serve.dart
  # Path of languages files
  languages_path: ./lib/languages
  # Type of languages files
  languages_type: json
  # Path of templates (widgets) files
  widgets_path: ./lib/widgets
  # Type of templates (widgets) files
  widgets_type: j2.html
  # Path of migrations files for different databases
  mysql_migrate:
    path: ./migrations
    type: sql
  # Path of migrations files for different databases
  sqlite_migrate:
    path: ./lib/dart_migration
    type: dart
  build_output: ./build_example
  public_path: ./public

Relative paths are resolved from the current directory in which the finch command is executed. Normally, commands should be run from the project root where pubspec.yaml is located. When ProjectCommands is created, the CLI also finds pubspec.yaml in this current directory and loads its finch section.

Application Entry Points

app

Specifies the main application file for this command:

finch run

In the example above, the CLI runs dart run for ./lib/app.dart. If --path or -p is supplied, the command-line value is used instead of app:

finch run --path ./lib/another_app.dart

If app is not configured, the CLI searches common directories such as bin, lib, and src for names such as app.dart and server.dart. If no file is found, it asks the user for a path.

Note: In the current implementation, finch build does not read the app key directly. Use --appPath or -a to select the build entry point. Otherwise, build checks the legacy internal path setting and then falls back to ./lib/app.dart.

serve

Specifies the development entry point for this command:

finch serve

In addition to running the selected file, this command enables the Dart VM Service so the development and reload workflow is available. The --path or -p option takes precedence over serve:

finch serve --path ./lib/watcher.dart

The configured file must exist in the project and provide a suitable application entry point.

Language Files

languages_path

Specifies the directory containing translation files. If this key is absent, the CLI default is ./lib/languages.

The finch build command copies this directory to lib/languages in the build output. The --langPath or -l option overrides this setting for the current build:

finch build --langPath ./lib/languages

If the path is empty or the directory does not exist, the language-copying step is skipped.

languages_type

Specifies the translation file extension without a leading dot. For files such as fa.json and en.json, use json.

When the application's internal build needs to convert translations to Dart, LanguageToDart reads only files with this extension and generates language_dart.g.dart inside languages_path. The default is json.

Templates

widgets_path

Specifies the Jinja template directory. If this key is absent, the CLI default is ./lib/widgets.

The finch build command copies this directory to lib/widgets in the build output. The --widgetPath or -w option takes precedence for the current build:

finch build --widgetPath ./lib/widgets

If the path is empty or the directory does not exist, the template-copying step is skipped.

widgets_type

Specifies the template extension without a leading dot. For files such as home.j2.html, the correct value is j2.html.

When the application's internal build converts templates to Dart, WidgetToDart converts files matching this extension into the template map and creates widget_dart.g.dart in widgets_path. The CLI default for this conversion is html.

Database Migrations

mysql_migrate

Contains the MySQL migration creation settings:

mysql_migrate:
  path: ./migrations
  type: sql

• path: Directory in which a new migration file is created.
• type: File extension and migration template type, usually sql.

These values are read by finch migrate --create and finch make:migration:

finch migrate --create --name create_users
finch make:migration --name create_users

The generated filename contains a timestamp, the migration name, and the configured extension. The --path or -p option on finch make:migration can override the directory for that invocation.

sqlite_migrate

Contains the SQLite migration creation settings:

sqlite_migrate:
  path: ./lib/dart_migration
  type: dart

When --sqlite or -s is supplied, the CLI reads this section instead of the MySQL settings:

finch make:migration --sqlite --name create_books
finch migrate --create --sqlite --name create_books

In the example project, the dart type creates a Dart migration in ./lib/dart_migration. This section selects where the CLI creates a new file. The paths used to execute registered migrations at runtime come from the application configuration and migration registration in FinchApp.

Build Output

build_output

Specifies the default output directory for finch build:

build_output: ./build_example

The build output contains the executable at lib/app.exe and, when available, copies of public files, language files, and templates. The --output or -o option takes precedence:

finch build --appPath ./lib/app.dart --output ./release

If the directory configured in build_output already exists, the CLI removes and recreates it for the new build. However, if an existing custom path is supplied with --output, the build stops to avoid overwriting it.

The default value when this key is absent is ./finch_build.

Public Files

public_path

Specifies the source directory for public files such as CSS, JavaScript, images, and fonts during the build step:

public_path: ./public

If this directory exists, finch build copies it to the public directory in the build output. The --publicPath or -p option on the build command takes precedence:

finch build --publicPath ./public

The default value when this key is absent is ./public. This setting only controls the source copied during build. The directory served by the running application must still be configured through FinchConfigs.publicDir.

Configuration Precedence

Where a CLI command provides a corresponding option, Finch selects the value in this order:

1. The option supplied on the command line
2. The value in the finch section of pubspec.yaml
3. The Finch CLI internal default

For example, in the following command, --output replaces build_output, while --appPath selects the build entry point:

finch build \
  --appPath ./lib/app.dart \
  --output ./release \
  --publicPath ./public \
  --langPath ./lib/languages \
  --widgetPath ./lib/widgets

Keep stable project paths in pubspec.yaml and use command-line options for temporary runs with different paths.