A single-page application ships one bundle and one render path. A document site ships HTML and adds behaviour where it is needed. Islands architecture sits between them: the page is a document, and each interactive zone is a separate island with its own hydration cost. HydraLine applies that to Flutter Web, where the default bundle is a rendering engine.
Code: HydraLine, MIT licensed.
Dart 3.9, Flutter 3.35, three packages on pub.dev: hydraline for the document core, hydraline_server for shelf and Dart Frog, hydraline_flutter for widgets, static generation and the island runtime.
One tree, two render paths
The core model is DocumentNode. The same tree streams from a server or compiles into a static dist/ folder, and the two paths cannot drift because there is one description of the page.
final page = DocumentRootNode(
head: buildHead(SeoMeta(
title: 'Espresso Machine',
description: 'Compact 15-bar espresso machine.',
)),
body: [
HeadingNode(level: 1, children: [TextNode('Espresso Machine')]),
ParagraphNode(children: [TextNode('Real HTML. Real rankings.')]),
IslandPlaceholderNode(
id: 'calculator',
directive: HydrationDirective.onVisible,
size: IslandSize(width: 640, height: 320),
state: {'price': 249},
),
...islandRuntime(),
],
);
The serializer writes semantic elements, and the island placeholder becomes a custom element with a reserved size and its props in data-state.
Level 0: no script at all
Static HTML, zero JavaScript. Disclosure widgets use details and summary, in-page navigation uses :target, images carry loading="lazy". A page at L0 is a page a crawler reads exactly as a person does.
This level covers more than it sounds. A documentation page, a blog post and most landing pages are content with links, and content with links is what search engines rank.
Level 1: vanilla JavaScript and HTMX
Tabs, forms, search and filters do not need a rendering engine. L1 adds about 8–14 KB of vanilla JavaScript and HTMX, and the page stays a DOM tree that a browser can paint without a canvas.
The threshold is the useful part of the design: most “app” behaviour in a marketing page is a form and a list, and both fit in L1.
Level 2: Flutter islands, on trigger
An island is an isolated interactive zone with a Flutter engine behind it. The engine loads on a trigger (HydrationDirective.onVisible is one), not on page load.
data-state carries props across the server to client boundary as JSON, and one engine instance hosts several islands in separate views through the multi-view API. Pages without islands never load the engine, which is the guarantee that makes the whole model worth using.
Reserving the space
Layout shift comes from content that arrives after the browser has laid out the page. An island declares IslandSize(width: 640, height: 320), and the placeholder reserves exactly that box through Declarative Shadow DOM.
CLS stays near zero, and the CI test in a real Chrome checks the number rather than trusting the CSS.
Serving it
final handler = const Pipeline()
.addMiddleware(hydralineMiddleware(HydralineConfig(
manifest: manifest,
builders: {'/': (req, data) => page},
cache: HydralineCache.inMemory(),
)))
.addHandler((req) => Response.ok('app shell'));
Streaming SSR, in-memory caching and ETag/304 come with the middleware. botUserAgentPattern exists for delivery decisions, and the builders never receive the User-Agent: bot and human get byte-identical bodies, and a CI test compares them.
The SEO payload
Head metadata is part of the model: canonical, hreflang, Open Graph and Twitter Card with image dimensions, and nine JSON-LD types. The sitemap generator splits at 50 000 addresses, and the audit CLI checks the result.
That is the difference between “we can render HTML” and “the site can be submitted and read”. A canonical that disagrees with the sitemap is a self-inflicted problem, and generating both from one tree removes the disagreement.
Safety at the type level
SafeUrl rejects javascript: and data: when the value is constructed, so an unsafe URL cannot reach an attribute. Escaping is context aware: text and attribute values take different paths. sanitizeHtml() strips inline event handlers, and runtime scripts carry integrity and crossorigin.
The XSS fuzz suite runs a million inputs against those paths, which is the only convincing way to make a claim about a sanitizer.
What is outside the package
It does not replace main(), MaterialApp or your router, and it does not migrate an app for you. A route moves to document or hybrid mode, the rest keeps running as it did. That is the reason it can be adopted one page at a time, and the reason a partial migration is not a special case.
Related: semantic table for the same preference for native markup over a widget layer, and modular php framework for the server-side counterpart that renders documents without a frontend build.