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(orflutter pub getin 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
webor 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.yamlassets 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.