Sparrow Kit
Sparrow Kit is a Dart-first, DOM-first web framework. Its native UI API
describes HTML-oriented interfaces that can be server-rendered and hydrated in
the browser. The separate sparrow_cli package also includes an Analyzer-based
compiler for a limited, documented subset of Flutter-style source.
Status: 2.0.0-experimental.1 is an experimental, unreleased candidate. It
is not available from pub.dev or a release Git tag. Do not treat this version
as production-ready or as a general Flutter Web replacement.
Package purpose
Use sparrow_kit when you want to author UI in Dart and render browser-native
HTML, CSS, and DOM. The package provides UI nodes, signals, server-side
rendering, DOM rendering, hydration, routing, and metadata primitives. It does
not include a production HTTP server or turn arbitrary Flutter widgets into
HTML.
The package requires Dart >=3.6.0 <4.0.0. The CLI/compiler requires Dart
>=3.9.0 <4.0.0.
Installation
For this unreleased candidate, use a local checkout. The following example
assumes the app directory is next to a checkout named sparrow_kit; adjust the
relative path for your layout:
dependencies:
sparrow_kit:
path: ../sparrow_kit/packages/sparrow_kit
Then resolve dependencies:
dart pub get
To use the project CLI from that app, add sparrow_cli as a development
dependency too:
dev_dependencies:
sparrow_cli:
path: ../sparrow_kit/packages/sparrow_cli
The release versioned install instructions will be valid after the candidate is published or its Git tag is available. See the repository release and installation notes.
Quick start: render HTML
Create bin/preview.dart in a Dart package with the dependency above:
import 'package:sparrow_kit/server.dart';
void main() {
final visits = Signal<int>(0);
final page = UiPage(
() => Column(
gap: 8,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Heading(1, 'Hello from Sparrow Kit'),
Row(
gap: 4,
children: [
const Text('Visits: '),
Text.bind('visit_count', visits),
],
),
],
),
);
print(renderToString(page, clientScript: null));
}
Run it with:
dart run bin/preview.dart
This server-only example prints a complete HTML document, including the
serialized initial signal state and text hydration markers. clientScript: null intentionally omits the browser bundle; it is useful for inspecting SSR
output, not for interactive hydration.
For an end-to-end project, add the CLI dependency and follow the
Sparrow-native workflow.
The sparrow init scaffold supplies matching server and browser entry points.
Core UI and layout APIs
Import package:sparrow_kit/ui.dart for the platform-neutral UI model.
Frequently used nodes include:
- Content:
Text,Heading, andRichText. - Layout:
Row,Column,Container,Padding,Margin,Expanded,Flexible,SizedBox,Stack,Positioned,Wrap, andGrid. - Responsive layout:
Responsive,ResponsiveValue, andResponsiveVisibility. - Interaction and state:
Button,EventTarget,TextField, selection controls,Signal<T>,Text.bind, andKeyedList<T>.
These are Sparrow Kit UiNode classes, not Flutter widgets. Layout maps to
normal HTML elements and CSS; browser and Flutter rendering behavior should
not be assumed to match.
See the UI contract and build guide for
the API contract, examples, and constraints. The public exports are listed in
lib/ui.dart, lib/server.dart, and
lib/sparrow_kit.dart.
SSR, HTML rendering, and hydration
StringRenderer renders an SsrComponent to an HTML document.
renderToString is the convenience function used in the quick start.
StaticSiteGenerator writes one index.html per explicitly declared
StaticPage. It does not discover pages by scanning source files.
In the browser, mountUi renders a client-only tree into an existing host
element. hydrateUiApp builds the same UiNode description against serialized
server state, checks the existing DOM, and attaches event listeners and signal
effects. Hydration does not replace the server-rendered root; a mismatch is an
explicit error. Call the returned disposer when the UI is removed to release
bindings and listeners.
For request-time rendering, applications provide their own HTTP server and
call the rendering APIs. Sparrow Kit includes a development server in
sparrow_cli, but it is not a production server adapter.
Responsive design
Sparrow's Responsive node requires a mobile layout and supports optional
tablet and desktop overrides. The default CSS minimum-width breakpoints are
600px for tablet and 1024px for desktop. Responsive spacing and grid values
use the same mobile-first model. These are CSS viewport rules, not Flutter
device classes, MediaQuery, or a general adaptive layout engine.
See responsive layouts and typography.
Routing and SEO
The routing package provides route definitions with path parameters, query
parameters, fragments, and browser history integration. A RouteCatalog can
share page and metadata definitions across browser navigation, request-time
rendering, and explicit static generation. See
routing and deferred loading
and routing and state.
HeadMetadata supports titles, descriptions, canonical URLs, robots
directives, custom meta tags, Open Graph, Twitter cards, and JSON-LD. When
StaticSiteGenerator receives a valid siteBaseUrl, it generates
sitemap.xml and robots.txt by default. Metadata and sitemap entries depend
on the application's supplied page data; Sparrow Kit does not guarantee
search ranking or validate the truth of that data. See
SSR, hydration, and SEO.
Browser requirements and limitations
Browser output requires JavaScript and standard DOM, history, and CSS support.
Serve generated assets over HTTP or HTTPS; file:// is not a substitute for
testing a deployed site. No formal browser-version compatibility matrix is
published. The visual regression suite currently uses Chromium on Windows;
other browser engines and operating systems have not been qualified.
The Flutter-style compiler is a separate CLI feature. It supports only the constructors, properties, expressions, and state patterns in the Flutter compiler reference. Unsupported forms produce diagnostics. It does not support arbitrary Flutter packages, render objects, custom painting, or general Flutter lifecycle behavior.
Further reading and examples
- Getting started
- SSR, hydration, and SEO
- Configuration and SEO
- Assets and fonts
- Deployment
- Sparrow-native UI example
- UI contract smoke example
Author
Sparrow Kit was created and developed by Min Thiha Aung.
Licensed under the MIT License.