Litro
Fullstack web framework for Lit components — file-based routing, streaming SSR, SSG, and Nitro deployment adapters. A standards-based Next.js / Nuxt.js alternative.
npm install @beatzball/litro pnpm add @beatzball/litro
A fullstack web framework for Lit components, powered by Nitro.
- File-based routing —
pages/index.ts→/,pages/blog/[slug].ts→/blog/:slug - Streaming SSR — Declarative Shadow DOM via
@lit-labs/ssr, streamed from the server - Client hydration —
LitroRouter(URLPattern-based) takes over after SSR with no flicker - Server data fetching —
definePageData()runs on the server, serialized to the client - Content layer —
litro:contentvirtual module for Markdown blogs with 11ty-compatible frontmatter - API routes — plain
server/api/files using H3 handlers - One port in dev — Vite and Nitro share a single HTTP port
- Any deployment — Node.js, Cloudflare Workers, Vercel Edge, static via Nitro adapters
Quick start
npm create @beatzball/litro@latest my-app
cd my-app
npm install
npm run dev
Hello World
// pages/index.ts
import { LitroPage, definePageData, html } from '@beatzball/litro/runtime';
import { customElement } from 'lit/decorators.js';
const pageData = definePageData(async () => ({
message: 'Hello from the server!',
}));
@customElement('page-index')
export default class IndexPage extends LitroPage {
override render() {
const data = this.serverData as typeof pageData | null;
return html`<h1>${data?.message}</h1>`;
}
}
How It Compares
| Litro | Next.js | Nuxt.js | |
|---|---|---|---|
| Component model | Lit | React | Vue |
| File-based routing | ✓ | ✓ | ✓ |
| SSR / SSG | ✓ | ✓ | ✓ |
| Server engine | Nitro | custom | Nitro |
| Hello World JS | ~8kB | ~90kB | ~60kB |
| Virtual DOM | — | ✓ | ✓ |
| W3C standard comps | ✓ | — | — |
Note on Hello World JS figures: approximate figures based on widely-cited community benchmarks and published framework documentation — not independently measured by this project. Lit's ~5 kB runtime size is documented on lit.dev. Next.js and Nuxt.js figures reflect commonly reported baseline JS payloads for a minimal page and vary by framework version and configuration.
SEO
Litro renders all pages server-side via Declarative Shadow DOM before sending HTML to the browser. Search engines receive fully-rendered content — the same approach used by Next.js and Nuxt.js. Client-side-only web components have SEO limitations; Litro's SSR eliminates them by default.
Documentation
Full documentation at litro.dev.
Packages
| Package | Description |
|---|---|
@beatzball/litro |
This package — core framework |
@beatzball/litro-router |
Standalone URLPattern router (zero dependencies) |
@beatzball/create-litro |
npm create @beatzball/litro scaffolding CLI |
License
Apache License 2.0 — Copyright 2026 beatzball.
Changelog
0.3.0
Minor Changes
-
619ec3c: feat(seo): inject seoHead and seoTitle from pageData into HTML shell
Pages can now return
seoHead(a string of meta/JSON-LD tags) andseoTitlefromdefinePageData(). The framework extracts these at request time and injects them into the actual<head>element of the HTML response — not buried in the__litro_data__JSON blob.Also bumps the
h3dependency to>=1.15.6to patch CVE GHSA-22cc-p3c6-wpvm.Also improves npm discoverability: updated descriptions and keywords for all three packages, and rewrote the framework README with a Hello World example, comparison table, and SEO section.
Patch Changes
-
d5d0b41: fix: strip seoHead/seoTitle from litro_data JSON; add .xml MIME type to litro preview
Pages returning
seoHeadfromdefinePageData()commonly include a JSON-LD<script>block. The closing</script>inside the JSON string caused the browser HTML parser to terminate the outer<script type="application/json">element early, leaking the remainder of the JSON as visible text and causinggetServerData()to return null. Fixed by destructuringseoHeadandseoTitleout of the page data beforeJSON.stringify— these fields are only needed server-side to build the<head>.Also adds
.xmlto the MIME type map inlitro preview's static file server, preventing browsers from prompting a download for.xmlroutes (e.g. RSS feeds, sitemaps) when previewing an SSG build locally. -
Updated dependencies [619ec3c]
- @beatzball/litro-router@0.1.5
0.2.0
Minor Changes
-
2456382: Add official documentation site and starlight recipe improvements
@beatzball/litro- Add
LITRO_BASE_PATHenv var support increate-page-handler.ts— prefixes the/_litro/app.jsscript URL for sub-path deployments (e.g. GitHub Pages project sites atowner.github.io/repo/) - Fix Lit hydration mismatch on SSR'd pages:
LitroPage.connectedCallback()now peeks at the__litro_data__script tag to setserverDatabefore Lit's first render, without consuming the tag - Fix layout shift on navigation:
LitroOutlet.firstUpdated()no longer eagerly clears SSR children — the router's atomic swap handles it
@beatzball/litro-router- Atomic DOM swap in
_resolve(): new element is appended hidden alongside old SSR content, waits forupdateComplete+requestAnimationFrame, then old content is removed and new element revealed — eliminates blank flash and layout shift during navigation _lastPathnameguard prevents re-render on hash-onlypopstateevents (TOC / fragment link clicks)
@beatzball/create-litro- Starlight recipe: rename
sl-card,sl-card-grid,sl-badge,sl-tabs,sl-tab-item,sl-aside→litro-card,litro-card-grid,litro-badge,litro-tabs,litro-tab-item,litro-asideto avoid collision with Shoelace's registered custom element names - Starlight recipe: integrate Shoelace (
@shoelace-style/shoelace) — tree-shaken component imports inapp.ts, icon assets at/shoelace/assets/, theme CSS at/shoelace/themes/;sl-buttonandsl-icon-buttonnow available in all scaffolded starlight sites - Starlight recipe:
litro-cardimprovements — equal-height cards via flex column, icon + title rendered inline side-by-side, newiconSrcprop for image-based icons - Starlight recipe: sticky header via
:host { position: sticky }(works correctly across shadow DOM boundary); sticky TOC matching sidebar behaviour - Starlight recipe: theme script falls back to
prefers-color-schemewhen no localStorage preference is set - Add
docs/workspace (@beatzball/litro-docs) — official Litro documentation site built on the starlight recipe, deployed to GitHub Pages via.github/workflows/docs.yml
- Add
Patch Changes
- Updated dependencies [2456382]
- @beatzball/litro-router@0.1.4
0.1.5
Patch Changes
- 3269a17: The content plugin now generates
litro-content.jsstubs using a path relative to the stub file rather than an absolute path. This prevents machine-specific directory paths from being baked into generated files.
0.1.4
Patch Changes
- 360e028:
litro devandlitro previewnow default to port 3000 and auto-increment when that port is taken, rather than crashing with an opaqueEADDRINUSEerror. A connect-based TCP probe detects all listeners including Docker Desktop's port-forwarding on macOS. Passing--port/-pexplicitly still errors out if that port is already in use.
0.1.3
Patch Changes
-
78fdaf6: Fix hash-only navigation re-renders, shadow DOM scroll-to-hash, SSG preview, and routeMeta.head injection.
@beatzball/litro-router- Hash-only
popstateevents (fragment/TOC links) no longer re-render the current page.LitroRouternow tracks_lastPathnameand skips_resolve()when only the hash changes. - After mounting a component, if
location.hashis set, the router waits forupdateCompletethen scrolls to the target element via_scrollToHash(). Heading elements inside shadow roots are located using_findDeep()recursive shadow DOM traversal — nativedocument.getElementById()cannot cross shadow boundaries.
@beatzball/litrocreatePageHandlernow forwardsrouteMeta.headtobuildShell(). Previously, stylesheet links and inline scripts declared inrouteMeta.headwere silently dropped from the HTML<head>.litro previewnow serves SSG builds fromdist/static/with a built-in Node.js static file server (clean-URL resolution, correct MIME types). Previously only SSR builds were handled andlitro previewafter an SSG build exited with "No production build found".- Fixed Node.js v22 DEP0190 deprecation:
spawn/spawnSynccalls with an args array andshell: truenow join into a single command string.
- Hash-only
-
Updated dependencies [78fdaf6]
- @beatzball/litro-router@0.1.3
0.1.2
Patch Changes
-
76d3bc7: fix: client-side navigation links do not work on first load
<litro-link>clicks were silently no-ops in scaffolded apps because of three compounding bugs.
Bug 1 — Empty route table on init (
LitroOutlet,app.ts)app.tssetoutlet.routesinside aDOMContentLoadedcallback (a macrotask). By that point Lit's first-update microtask had already fired, sofirstUpdated()ran withroutes = []and the router was initialised with no routes.Fix —
LitroOutlet: Replace@property({ type: Array }) routeswith a plain getter/setter. The setter callsrouter.setRoutes()directly when the router is already initialised, without going through Lit's render cycle (which would crash with "ChildPart has no parentNode" becausefirstUpdated()removes Lit's internal marker nodes to give the router ownership of the outlet's subtree).Fix —
app.ts(fullstack recipe template + playground): Setoutlet.routessynchronously after imports rather than inside aDOMContentLoadedcallback. Module scripts are deferred by the browser; by the time they execute the DOM is fully parsed and<litro-outlet>is present.
Bug 2 — Click handler never attached on SSR'd pages (
LitroLink)@lit-labs/ssraddsdefer-hydrationto custom elements inside shadow DOM.@lit-labs/ssr-clientpatchesLitElement.prototype.connectedCallbackto block Lit's update cycle when this attribute is present. A@clickbinding on the shadow<a>is a Lit binding — it is never attached untildefer-hydrationis removed, which only happens when the parent component hydrates. For page components that are never hydrated client-side (because the router replaces the SSR content before they load),<litro-link>elements inside them never receive a click handler.This is why the playground appeared to work: its home page has no
<litro-link>elements. The fullstack generator template does, so clicks on the SSR'd page were silently ignored.Fix: Move the click handler from a
@clickbinding on the shadow<a>to the HOST element viaaddEventListener('click', ...)registered inconnectedCallback()(beforesuper.connectedCallback()). The host listener runs inLitroLink's ownconnectedCallbackoverride, which executes before the@lit-labs/ssr-clientpatch checks fordefer-hydration. This ensures the handler is active immediately after the element connects to the DOM, even for SSR'd elements on first load.The shadow
<a>is kept without a@clickbinding — it exists for progressive enhancement (no-JS navigation) and accessibility (cursor, focus, keyboard navigation).
Bug 3 —
_resolve()race condition (LitroRouter)setRoutes()calls_resolve()immediately for the current URL. If the user clicks a link before that initial_resolve()completes (e.g. while the page action's dynamic import is in flight), a second_resolve()call starts concurrently. If the first call (for/) completes after the second (for/blog), it overwrites the blog page with the home page.Fix: Add a
_resolveTokenmonotonic counter. Each_resolve()call captures its own token at the start and checks it after everyawait. If the token has advanced, a newer navigation superseded this one and the call returns without touching the DOM.
Bug 4 —
@property()decorators silently dropped by esbuild TC39 transform (LitroLink)esbuild 0.21+ uses the TC39 Stage 3 decorator transform. In that mode, Lit's
@property()decorator only handlesaccessorfields; applied to a plain field (href = '') it is silently not applied. As a resulthref,target, andrelwere absent fromobservedAttributes, soattributeChangedCallbackwas never called during element upgrade, leavingthis.href = ''forever regardless of what the HTML attribute said.Fix: Replace the three
@property()field decorators with astatic override properties = { href, target, rel }declaration. Lit reads this static field at class-finalization time viafinalize(), which runs before the element is defined incustomElements, ensuring the properties are correctly registered inobservedAttributes.
Adds a new
LitroOutlet.test.tstest file (6 tests) covering the synchronous and late-assignment code paths, the setter guard, SSR child clearing, and theLitroRouterconstructor call.Updates
LitroLink.test.ts(12 tests) to dispatch realMouseEvents on the host element (exercising theaddEventListenerpath) rather than calling the private handler directly by name.
Template fix —
@state() declare serverDataincompatible with jiti/SSGThe fullstack recipe template used
@state() declare serverData: T | nullto narrow theserverData: unknowntype inherited fromLitroPage. Thedeclaremodifier emits no runtime code, but jiti's oxc-transform (used in SSG mode to load page files) throws "Fields with the 'declare' modifier cannot be initialized here" under TC39 Stage 3 decorator mode.Fix: Remove
@state() declare serverDatafrom both page templates. Use a local type cast inrender()instead:const data = this.serverData as T | null. The property is already reactive (declared as@state() serverData = nullinLitroPage). UpdatedLitroPage.tsJSDoc andDECISIONS.mdto document this pattern and warn againstdeclarefields in subclasses. -
Updated dependencies [76d3bc7]
- @beatzball/litro-router@0.1.2
0.1.1
Patch Changes
- 6a8da0e: Update all README references to use
@beatzballscoped package names following the rename in v0.1.0. Fixes install commands,pnpm --filterflags,npm createcommands, and import paths. - Updated dependencies [6a8da0e]
- @beatzball/litro-router@0.1.1
0.1.0
Minor Changes
-
618a9b8: Rename all packages to
@beatzballscope. The unscopedlitropackage was blocked by npm's name-similarity protection (too close tolit,listr, etc.). All three packages are now published under the@beatzballorg scope:litro→@beatzball/litrolitro-router→@beatzball/litro-routercreate-litro→@beatzball/create-litro
The previously published unscoped
litro-router@0.0.2andcreate-litro@0.0.2are deprecated on npm with a redirect notice.
Patch Changes
- Updated dependencies [618a9b8]
- @beatzball/litro-router@0.1.0
0.0.2
Patch Changes
- 4552934: Add
license,repository, andpublishConfigfields to all published packages; configure Changesets for automated version management, per-package changelogs, and npm publishing via GitHub Actions. - Updated dependencies [4552934]
- litro-router@0.0.2