Flutter SQLite Scaffold

flutter_sqlite_scaffold is a globally installed Dart CLI that generates Flutter SQLite code from a schema.sql file.

It can generate models, SQLite services, validation, CRUD screens, auth, WebView navigation, profile screens, SMTP email support, and starter tests.

This is a CLI tool. Do not add flutter_sqlite_scaffold to the dependencies section of the Flutter project being generated.

Requirements

  • Flutter 3.x with Dart 3.x
  • Flutter and Dart available from the terminal

Check the local installation:

flutter --version
dart --version

Install Globally

Install the latest published version once:

dart pub global activate flutter_sqlite_scaffold

Verify the command:

fss --version
fss doctor

Command Not Found

Pub installs global executables into its cache bin directory. That directory must be included in the user PATH.

On Windows, run the included setup command:

dart pub global run flutter_sqlite_scaffold:fss_setup_path

Close and reopen the terminal, then verify:

fss --help

The usual Windows path is:

%LOCALAPPDATA%\Pub\Cache\bin

If PUB_CACHE is configured, use %PUB_CACHE%\bin instead.

On macOS or Linux using Zsh:

echo 'export PATH="$PATH:${PUB_CACHE:-$HOME/.pub-cache}/bin"' >> ~/.zshrc
source ~/.zshrc

For Bash, add the same line to ~/.bashrc.

Update

Upgrade the globally installed command:

dart pub global activate flutter_sqlite_scaffold

Install a specific version:

dart pub global activate flutter_sqlite_scaffold 1.1.3

Uninstall

dart pub global deactivate flutter_sqlite_scaffold

Generate A Project

Create a normal Flutter project first:

flutter create utc2_app
cd utc2_app

Create the starter SQL schema:

fss init-schema

Edit schema.sql, then generate into the current Flutter project:

fss --schema schema.sql --project . --name utc2_app

When feature flags are omitted, fss asks interactive questions.

Generation replaces generated project files including lib/, test/, pubspec.yaml, and analysis_options.yaml. Use a new Flutter project or commit existing work before running the command.

After generation:

flutter pub get
flutter run

For Flutter Web:

flutter run -d chrome

The generator detects the Flutter and Dart SDK installed on the machine and writes compatible SDK and dependency constraints into the generated project.

Non-Interactive Example

Generate the UTC2 auth flow with SQLite, SMTP email, and a WebView destination:

fss \
  --schema schema.sql \
  --project . \
  --name utc2_app \
  --with-auth \
  --with-email \
  --no-email-screen \
  --no-splash \
  --no-profile \
  --no-home \
  --login-target webview \
  --forgot-password email \
  --no-remember-me \
  --no-edit-profile \
  --gender-widget dropdown

PowerShell accepts the same command on one line:

fss --schema schema.sql --project . --name utc2_app --with-auth --with-email --no-email-screen --no-splash --no-profile --no-home --login-target webview --forgot-password email --no-remember-me --no-edit-profile --gender-widget dropdown

Commands

fss --help
fss --version
fss doctor
fss init-schema

Main generation options:

  • --schema, -s: SQL schema path.
  • --project, -p: Flutter project directory.
  • --out, -o: Alias for --project.
  • --name, -n: Generated Dart package name.
  • --with-auth / --no-auth: Enable or disable authentication.
  • --with-email / --no-email: Enable or disable SMTP support.
  • --with-email-screen / --no-email-screen: Control the standalone email screen.
  • --with-splash / --no-splash: Control the splash screen.
  • --with-profile / --no-profile: Control profile generation.
  • --with-home / --no-home: Enable or disable dashboard and CRUD modules.
  • --login-target home|webview|success: Select the post-login destination.
  • --forgot-password local|email: Select the password recovery mode.
  • --remember-me / --no-remember-me: Control persistent login.
  • --edit-profile / --no-edit-profile: Control profile editing.
  • --gender-widget dropdown|radio: Select the gender input widget.
  • --logo-source url|asset: Select a network or local UTC2 logo.

Options that require authentication (--login-target, --forgot-password, --remember-me, --edit-profile, and --logo-source) automatically enable auth. --edit-profile also enables the profile screen. A later --no-auth or --no-profile still disables the related feature.

The success login target is the basic success screen, so it cannot be combined with --with-home. Use home for dashboard/CRUD or webview when the dashboard should still be generated but is not the first post-login page.

Schema Example

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT NOT NULL UNIQUE,
  password TEXT NOT NULL,
  student_id TEXT NOT NULL,
  full_name TEXT NOT NULL,
  gender TEXT NOT NULL CHECK(gender IN ('Nam', 'Nữ', 'Khác'))
);

Column names and SQL constraints are used to select generated widgets and validators. For example, email columns receive email validation and CHECK(field IN (...)) values become dropdown or radio options.

Email Configuration

Email-enabled projects contain:

lib/config/email_config.dart
lib/config/email_config.example.dart

Set the Gmail sender address and Gmail app password in email_config.dart. Do not commit real SMTP credentials.

Local Package Development

This section is only for contributors developing this CLI package:

dart pub get
dart pub global activate --source path .
fss --version

To return to the published version:

dart pub global deactivate flutter_sqlite_scaffold
dart pub global activate flutter_sqlite_scaffold

Before publishing:

dart analyze
dart pub publish --dry-run
dart pub publish

Libraries

flutter_sqlite_scaffold