Litro
Litro's adapter system lets you choose which web component framework powers your project. All three adapters share the same infrastructure — file-based routing, definePageData(), LitroRouter, content layer, SSG, deployment adapters — only the component authoring model differs.
Available Adapters
| Adapter | Framework | DOM Model | SSR Strategy | Hydration | CSS Scoping |
|---|---|---|---|---|---|
| lit (default) | Lit 3 | Shadow DOM | @lit-labs/ssr (DSD) | Yes | Shadow DOM |
| fast | FAST Element 2 | Shadow DOM | @microsoft/fast-ssr (DSD) | Yes | Shadow DOM |
| elena | Elena | Light DOM | Direct rendering | No (progressive enhancement) | @scope CSS |
Choosing an Adapter
Use Lit if you want the most mature web component library with the largest ecosystem, decorator-based APIs, and first-class TypeScript support. This is the default and most battle-tested option.
Use FAST Element if you prefer Microsoft's observable-based reactivity model, auto-generated attributes, or need compatibility with Fluent UI Web Components.
Use Elena if you want light DOM rendering — no Shadow DOM boundaries, global CSS reaches component internals, smaller HTML payloads, and no hydration overhead. Best for content-heavy sites where progressive enhancement is preferred over client-side hydration.
Creating a Project
The --adapter flag selects the framework at project creation:
# Lit (default — can omit the flag)
pnpm create @beatzball/litro my-app --adapter lit
# FAST Element
pnpm create @beatzball/litro my-app --adapter fast
# Elena
pnpm create @beatzball/litro my-app --adapter elena
Or omit --adapter and choose interactively during scaffolding.
What Stays the Same
Regardless of which adapter you choose, these features work identically:
- File-based routing —
pages/directory convention, dynamic segments, catch-all routes definePageData()— server-side data fetching, serialized into the HTML shellLitroRouter— client-side SPA navigation via<litro-link>andhistory.pushState- Content layer —
litro:contentvirtual module for Markdown - API routes —
server/api/with H3 handlers - SSG —
generateRoutes()for static prerendering - Deployment — all Nitro presets (Cloudflare, Vercel, Node.js, etc.)
- Recipes — fullstack, 11ty-blog, and starlight recipes work with all adapters
What Differs
Each adapter provides its own native implementations of three internal components:
| Component | Purpose |
|---|---|
| LitroOutlet | Mounts the router, serves as the container for route content |
| LitroLink | Intercepts clicks for SPA navigation, falls back to <a> |
| LitroPage | Reads __litro_data__ before first render, exposes serverData |
These are imported from adapter-specific paths — see each adapter's guide for details.
Per-Adapter Guides
- Lit Adapter — Shadow DOM, DSD SSR, decorator API
- FAST Element Adapter — Shadow DOM, DSD SSR, observable API
- Elena Adapter — Light DOM, direct SSR, mixin API
- Switching Adapters — migration guide for existing projects