@flightdev/ui

The universal UI framework layer for Flight. Provides server-side rendering (SSR) and hydration support for 18+ UI frameworks.

Table of Contents

• Installation
• Quick Start
• Architecture
• Adapter Registry
• Rendering
• API Reference
• License

Installation

npm install @flightdev/ui

Then install the adapter for your framework:

npm install @flightdev/ui-react    # React 18+
npm install @flightdev/ui-vue      # Vue 3
npm install @flightdev/ui-angular  # Angular 17+
npm install @flightdev/ui-svelte   # Svelte 5
npm install @flightdev/ui-solid    # Solid.js
npm install @flightdev/ui-qwik     # Qwik

Quick Start

import { defineUI, renderPage, toHTML } from '@flightdev/ui';
import { react } from '@flightdev/ui-react';

// Define UI configuration
const ui = defineUI(react());

// Render a component
const result = await renderPage(ui, {
    component: App,
    props: { user: { name: 'John' } },
});

// Generate full HTML document
const html = toHTML(result, {
    title: 'My App',
    lang: 'en',
});

Architecture

The UI system is organized into three tiers based on feature support:

Tier 1: Full Support

Full SSR, streaming, hydration, and islands architecture support.

| Adapter | Package | Streaming | Islands | Resumable | |---------|---------|-----------|---------|-----------| | React 18+ | @flightdev/ui-react | Yes | Yes | No | | Vue 3 | @flightdev/ui-vue | Yes | Yes | No | | Angular 17+ | @flightdev/ui-angular | Yes | Yes | No | | Svelte 5 | @flightdev/ui-svelte | No | Yes | No | | Solid.js | @flightdev/ui-solid | Yes | Yes | No | | Qwik | @flightdev/ui-qwik | Yes | Yes | Yes |

Tier 2: Standard Support

SSR and hydration with framework-specific optimizations.

| Adapter | Package | |---------|---------| | Preact | @flightdev/ui-preact | | Lit | @flightdev/ui-lit | | Marko | @flightdev/ui-marko | | Stencil | @flightdev/ui-stencil | | Mithril | @flightdev/ui-mithril | | Inferno | @flightdev/ui-inferno |

Tier 3: HTML-First

Server-rendered HTML with minimal JavaScript.

| Adapter | Package | |---------|---------| | HTMX | @flightdev/ui-htmx | | Alpine.js | @flightdev/ui-alpine | | Hotwire | @flightdev/ui-hotwire | | Stimulus | @flightdev/ui-stimulus | | Petite-vue | @flightdev/ui-petite-vue | | Vanilla | @flightdev/ui-vanilla |

Adapter Registry

The adapter registry provides dynamic loading and capability queries.

Registering Adapters

import { adapterRegistry, registerBuiltinAdapters } from '@flightdev/ui';

// Register all built-in adapters
registerBuiltinAdapters();

Getting Adapters

// Get adapter by name
const adapter = await adapterRegistry.get('react');

// Get adapter metadata
const metadata = adapterRegistry.getMetadata('vue');
console.log(metadata.tier);       // 'tier-1'
console.log(metadata.framework);  // 'vue'

Querying Capabilities

// List adapters by tier
const tier1 = adapterRegistry.listByTier('tier-1');
// ['react', 'vue', 'angular', 'svelte', 'solid', 'qwik']

// List adapters by capability
const streaming = adapterRegistry.listByCapability('streaming');
// ['react', 'vue', 'angular', 'solid', 'qwik', 'marko']

// Check if adapter has capability
const hasStreaming = adapterRegistry.hasCapability('react', 'streaming');
// true

Rendering

String Rendering

Render a component to an HTML string:

const result = await adapter.renderToString({
    component: App,
    props: { data },
});

console.log(result.html);            // Rendered HTML
console.log(result.hydrationData);   // State for client hydration
console.log(result.timing);          // Performance metrics

Streaming Rendering

For adapters with streaming support:

const { stream, done, abort } = adapter.renderToStream(
    { component: App, props: {} },
    { url: request.url },
    {
        onShellReady: () => {
            response.writeHead(200, {
                'Content-Type': 'text/html',
                'Transfer-Encoding': 'chunked',
            });
        },
        onError: (error) => {
            console.error('Render error:', error);
        },
    }
);

const reader = stream.getReader();
while (true) {
    const { done: readerDone, value } = await reader.read();
    if (readerDone) break;
    response.write(value);
}
response.end();

Hydration Scripts

Generate client-side hydration code:

const result = await adapter.renderToString({ component: App, props: {} });
const hydrationScript = adapter.getHydrationScript(result);

const html = `
<!DOCTYPE html>
<html>
<body>
    <div id="app">${result.html}</div>
    ${hydrationScript}
</body>
</html>
`;

API Reference

defineUI

Create a UI configuration object.

function defineUI(
    adapter: UIAdapterV2 | UIAdapterV1,
    options?: {
        streaming?: boolean;
        hydration?: 'full' | 'partial' | 'progressive' | 'none';
        islands?: boolean;
        defaultIslandStrategy?: IslandHydrationStrategy;
    }
): UIConfig;

renderPage

Render a component with the configured adapter.

function renderPage(
    config: UIConfig,
    component: Component,
    context?: RenderContext
): Promise<RenderResult>;

toHTML

Generate a full HTML document from a render result.

function toHTML(
    result: RenderResult,
    options?: {
        lang?: string;
        title?: string;
        meta?: Record<string, string>;
        charset?: string;
        viewport?: string;
    }
): string;

BaseUIAdapter

Base class for creating custom adapters.

import { BaseUIAdapter } from '@flightdev/ui';
import type { Component, RenderResult, RenderContext } from '@flightdev/ui';

class MyAdapter extends BaseUIAdapter {
    readonly id = 'my-adapter';
    readonly name = 'My Adapter';
    readonly framework = 'my-framework';
    readonly tier = 'tier-2' as const;

    async renderToString(
        component: Component,
        context?: RenderContext
    ): Promise<RenderResult> {
        // Implementation
    }

    getHydrationScript(result: RenderResult): string {
        // Implementation
    }

    getClientEntry(): string {
        // Implementation
    }
}

Documentation

For detailed documentation on each adapter and advanced patterns:

• Adapter System
• Usage Patterns

License

MIT