Sparrow CLI

sparrow_cli provides the sparrow command for creating and building Sparrow-native web projects and compiling a documented subset of Flutter-style Dart applications to Sparrow's web runtime.

Status: 2.0.0-experimental.1 is an experimental, unreleased candidate. It is not available from pub.dev or a release Git tag. The Flutter-style compiler is not a general Flutter-to-Web compiler and is not a production-readiness guarantee.

Requirements and installation

The CLI requires Dart >=3.9.0 <4.0.0. sparrow kit build web also requires a Flutter project with its dependencies resolved; the command uses the Dart SDK bundled with that Flutter installation for the project's analysis and JavaScript compilation.

For the current unreleased candidate, use a local checkout. If your app is next to a checkout named sparrow_kit, add:

environment:
  sdk: '>=3.9.0 <4.0.0'

dependencies:
  sparrow_kit:
    path: ../sparrow_kit/packages/sparrow_kit

dev_dependencies:
  sparrow_cli:
    path: ../sparrow_kit/packages/sparrow_cli

Set the application's SDK constraint to >=3.9.0 <4.0.0, adjust the paths for your directory layout, and run:

dart pub get

Invoke the local executable with dart run sparrow_cli. After a published package or release Git tag becomes available, install instructions will be listed in the repository README.

Commands

Command Purpose
sparrow init [directory] Create or initialize a Sparrow-native project. sparrow create is an alias.
sparrow add web [app-directory] Add Sparrow web files and dependencies to an existing Dart app.
sparrow dev [--host HOST] [--port PORT] [--define NAME=VALUE] Build and serve a Sparrow-native project with file watching and browser reload. Defaults to 127.0.0.1:8080.
sparrow build web [--define NAME=VALUE] Build a Sparrow-native project configured by sparrow.json.
sparrow kit build web [--define NAME=VALUE] Build a Flutter app that stays within the compiler's supported subset.

Use dart run sparrow_cli --help to display the command summary. The development server is intended for local development; it is not a production HTTP server.

Sparrow-native workflow

Create a new directory, add the local path dependencies shown above to its pubspec.yaml, and initialize the project. Supplying the local paths first keeps this unreleased candidate from resolving to a remote branch:

mkdir my_site
cd my_site
dart pub get
dart run sparrow_cli init .
dart pub get
dart run sparrow_cli dev

The scaffold includes sparrow.json, a browser entry, a server entry, a minimal HTML shell, and a shared UiNode page. Existing files are left in place. Open http://127.0.0.1:8080/; stop the server with Ctrl+C.

Build production output with:

dart run sparrow_cli build web

The build analyzes the configured client and server entries, copies web assets, runs the server entry to generate HTML, compiles the browser entry with dart compile js -O2, and publishes the completed output to build/web/ by default. Production source maps and the compiler dependency manifest are omitted. The previous output is retained if a build fails before publication.

The output typically contains index.html, main.dart.js, copied files from web/, and any nested static route pages emitted by the server entry. SEO files are generated only when configured by the application. Serve the directory over HTTP for local inspection, for example:

python -m http.server 8000 --directory build/web

The server entry owns the explicit routes and page metadata. The CLI does not infer pages by scanning lib/. See the Sparrow UI and build guide and getting started.

Flutter-style compiler workflow

The Flutter application's pubspec.yaml must declare:

dependencies:
  flutter:
    sdk: flutter
  sparrow_kit:
    path: ../sparrow_kit/packages/sparrow_kit
  web: ^0.5.0

dev_dependencies:
  sparrow_cli:
    path: ../sparrow_kit/packages/sparrow_cli

Adjust the local paths, resolve dependencies, then run from the Flutter project root:

flutter pub get
dart run sparrow_cli kit build web

The CLI verifies that the project declares Flutter, sparrow_kit, and web. On a successful first run it creates missing integration configuration under sparrow_kit_web/ and compiler-owned intermediate entries under .dart_tool/sparrow_kit/. It does not rewrite the application's original lib/ files. The default production output is build/web/.

The Analyzer-based compiler lowers only the constructs in the Flutter compiler reference. Unsupported widgets, properties, and Dart patterns produce diagnostics. Custom painting, arbitrary Flutter packages, full Flutter lifecycle behavior, and the complete Material implementation are outside its scope.

Troubleshooting

  • Dependency or SDK resolution fails: check the Dart SDK constraint and local package paths, then run dart pub get (or flutter pub get in a Flutter project).
  • Flutter build reports a missing Flutter SDK package: confirm the project's manifest includes flutter: sdk: flutter, use an installed Flutter SDK, and resolve the app dependencies before building.
  • A required package is missing: add it to the application manifest. The compiler does not add web or other missing app dependencies automatically.
  • A widget or property is rejected: use the exact form in the compatibility reference; the compiler deliberately diagnoses unsupported input instead of silently approximating it.
  • A route or asset is missing: declare supported static routes and pubspec.yaml assets as described in routing and deferred loading and assets and fonts.
  • A generated page fails to load when opened directly from disk: serve build/web/ over HTTP and verify route handling on the target static host.

More details are in troubleshooting, deployment, and the root project README.

Author

Sparrow CLI was created and developed by Min Thiha Aung.

Licensed under the MIT License.

Libraries

sparrow_cli