Skip to main content

sparrow_kit 2.0.0-experimental.1 copy "sparrow_kit: ^2.0.0-experimental.1" to clipboard
sparrow_kit: ^2.0.0-experimental.1 copied to clipboard

Platformweb

A DOM-first Dart web framework with fine-grained reactivity, SSR, and SEO.

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, and RichText.
  • Layout: Row, Column, Container, Padding, Margin, Expanded, Flexible, SizedBox, Stack, Positioned, Wrap, and Grid.
  • Responsive layout: Responsive, ResponsiveValue, and ResponsiveVisibility.
  • Interaction and state: Button, EventTarget, TextField, selection controls, Signal<T>, Text.bind, and KeyedList<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.

1
likes
120
points
96
downloads

Documentation

API reference

Publisher

verified publishersparrowkit.site

Weekly Downloads

A DOM-first Dart web framework with fine-grained reactivity, SSR, and SEO.

Repository (GitHub)

License

MIT (license)

Dependencies

web

More

Packages that depend on sparrow_kit