Litro
Fullstack web framework for web components — choose Lit, FAST Element, or Elena via an adapter. 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 web components, powered by Nitro.
- Framework adapters — choose Lit (default), FAST Element, or Elena via
--adapter - File-based routing —
pages/index.ts→/,pages/blog/[slug].ts→/blog/:slug - Streaming SSR — Declarative Shadow DOM (Lit/FAST) or light DOM (Elena)
- 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
npm create @beatzball/litro@latest my-app
# pnpm
pnpm create @beatzball/litro my-app
# yarn
yarn create @beatzball/litro my-app
# bun
bun create @beatzball/litro my-app
# deno
deno init --npm @beatzball/litro my-app
cd my-app
pnpm install
pnpm dev
Hello World
// pages/index.ts
import { html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { LitroPage } from '@beatzball/litro/runtime';
import { definePageData } from '@beatzball/litro';
export 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 { message: string } | null;
return html`<h1>${data?.message}</h1>`;
}
}
How It Compares
| Litro | Next.js | Nuxt.js | |
|---|---|---|---|
| Component model | Lit / FAST / Elena | 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 before sending HTML to the browser — via Declarative Shadow DOM (Lit/FAST) or light DOM (Elena). 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 — fullstack, 11ty-blog, starlight, and supernova recipes |
License
Apache License 2.0 — Copyright 2026 beatzball.
Changelog
0.17.6
Patch Changes
- bf1e014: Stop promising a CommonJS entry point that was never built.
mainand therequirecondition on the root export both pointed atdist/index.cjs, a file absent from every published tarball, so anything resolving therequirecondition failed with a confusing error about a path it never asked for. The package is ESM only, as the other 32 export subpaths already said, and a CommonJS consumer now gets a clear resolution error naming the package instead.
0.17.5
Patch Changes
- 3fef4a0: Publish only
dist,assets, the content type declarations and the changelog. The tarball no longer carries TypeScript sources, test files, vitest config ortsconfig.tsbuildinfo: 575 files and 2.15 MB unpacked become 286 files and 0.77 MB. - cf4f575: Update
satorito 0.33.5 andserovalto 1.7.3, clearing four security advisories published on 2026-10-27 and 2026-10-28. Open Graph images render byte-for-byte the same after the satori update: the only API changes across the range are optional new options, and the font this package ships is a static instance, so the variable-font handling added upstream does not apply. - Updated dependencies [3fef4a0]
- @beatzball/litro-router@0.3.2
0.17.4
Patch Changes
-
4569da2: Warn by name when Lit's hydration support never installed, and raise the
vitedependency range from^8.0.16to^8.1.6.LitroOutlet.firstUpdated()now readsLitElement.observedAttributesand, ifdefer-hydrationis missing, logs oneconsole.errornaming the cause and the fix. The hydrate-support module only assignsglobalThis.litElementHydrateSupport;lit-elementreads that hook once, when its own module body runs, and the?.it reads it with makes a missing hook a permanent silent no-op. Until now that failed with no error at all: the build exited 0, the prerendered HTML was correct, and the browser threw the server's work away and re-rendered every page. Upgrading surfaces the fault in an existing app with no change to the app. It warns rather than throws, because a page that re-rendered still works and breaking it would turn a slow page into a dead one.The
viterange moves off^8.0.16now that the ordering fault is fixed, so alitro devserver starts from a release patched against GHSA-587h-7wmj-h5pm (High, CVSS 7.5) and four lower-severity advisories. All five are in the Vite dev server, and all five were fixed in 8.1.6, which Litro could not take while Vite 8.1+ broke hydration.^8.0.16still permitted 8.0.16 itself, so the floor had to move, not just the lockfile.src/runtime/client.tsis unchanged in behavior. Its header no longer claims that importing the hydrate support first is sufficient, and says plainly that the module is a library barrel and must not be used as an app's client entry — its named exports needlit-elementsynchronously, so it cannot be the two-statement bootstrap that recipes now scaffold. -
b8892c3: A page file may now carry a prefix before the bracket:
pages/@[handle].tsscans as/@:handleandpages/@[handle]/[statusId].tsas/@:handle/:statusId, so Mastodon-style/@alice@example.socialURLs are served. Before, the file scanned as the static path/@[handle]and the URL answered 404 (issue 234).A prefixed route now sorts before a bare param sibling, so
pages/@[handle].tsstill wins next topages/[slug].ts. Within dynamic routes, the route with more literal text in its path comes first; ties keep the old string order. No route in the recipes or the example apps changes the page it serves.A prefix may use letters, digits and
_ ~ @ ! & ' , ; = -. Any other character is rejected at scan time, because the client router or the server matcher reads it as pattern syntax or receives it percent-encoded.The suffix form (
[id].html.ts,[id]x.ts) is not supported and is tracked separately. A prefixed catch-all or optional (@[...all].ts,@[[lang]].ts) and any other stray bracket are rejected at scan time with an error that names the file. Before, they scanned as inert static paths. A non-page file with a bracket in its name, such aspages/[id].stories.ts, is now an error too; move it out ofpages/or start its name with-.During
litro dev, a page scan that fails on reload (one of the errors above, or a duplicate component tag) is logged and the server keeps serving the last good routes. Before, it stopped the dev server.litro buildstill fails.isDynamicnow comes from the bracket syntax, not from the spelling of the path. A file literally namedpages/:slug.tsused to be marked dynamic and is now a static route for the path/:slug.The OG image handler's route matcher now escapes the literal runs between params, so a bracket or a dot in a static part of a path matches itself.
-
dbaa8ea: Refuse two page files that derive the same component tag.
pages/index.tsis special-cased topage-home, so addingpages/home.tsnext to it used to kill the server at startup withFailed to execute 'define' on 'CustomElementRegistry': the name "page-home" has already been used with this registry, and/went down with/home. The page scan now fails first, inlitro dev,litro buildand the static build alike, with one clear error that names the tag and every page file that claims it. The root index tag stayspage-homefor now; renaming it topage-indexis a breaking change deferred to the next major.
0.17.3
Patch Changes
- 95b6336: Bump the
serovalproduction dependency from^1.3.0to^1.6.3, resolving GHSA-p6vx-979v-rg4c (Critical, CVSS 9.8) and GHSA-jp82-f5mq-hwhp (High, CVSS 7.5). Both advisories land onfromJSON(), which the Server Actions serializer calls on every response it decodes, so this is a reachable path rather than a baseline entry.
0.17.2
Patch Changes
- 12c9a22: The HTML shell no longer emits comments. The rationale for the synchronous DSD
polyfill script and for the app bundle's URL moved into TypeScript comments in
shell.ts, andfootno longer closes with<!-- /page-name -->, which nothing read. Every byte of a comment in the shell was served on every page of every Litro app.buildShell()'s first parameter is now_componentTag; the signature is unchanged, so callers do not have to change.
0.17.1
Patch Changes
-
4cdba19: Server-render
<litro-link>, and put the skip links inside a landmark.<litro-link>builds its<a href>inrender(), and the element was never registered on the server, so SSR emitted a bare<litro-link href="/docs">with no shadow root. The href sat on a custom element the browser will not follow, which left every such link unclickable with JavaScript turned off. Each adapter now imports its own link module frommanifestPreamble(), so the element is in the server bundle and every app renders a real anchor. An app no longer needs a side-effect import of@beatzball/litro/runtime/LitroLink.jsin one of its pages to make its links work.buildShellwrote its skip links as bare anchors at the top of<body>, outside every landmark, which axe-core reported asregionon every page a Litro app served. They now sit in a<nav aria-label="Skip links">. The label keeps the landmark distinct from a site's own navigation, and an emptyskipLinksarray emits no wrapper. Existing behavior is unchanged: the class stays on each anchor, so the shell's script still focuses the target and still hides a link whose target is missing.Also adds
./adapter/fast/runtime/*.jsand./adapter/elena/runtime/*.jsto the package exports, matching the existing./runtime/*.jsentry. -
Updated dependencies [818ba3f]
- @beatzball/litro-router@0.3.1
0.17.0
Minor Changes
-
bfe941d: Add
litro mcp serve: serves one agent's tools, and theui://documentslitro mcp-app buildpacked, to an MCP host over stdio.The command is thin. It compiles the project's source with the project's own Vite config — not jiti, which mis-orders the decorator passes — loads
@beatzball/litro-agent/mcp-serverfrom the project's dependencies at run time, and keepsstdoutfor JSON-RPC and nothing else: the real stream is handed to the MCP transport andprocess.stdout.writeis pointed at stderr before Vite starts, so a project's ownconsole.logcannot desync the framing.Flags:
--project <dir>when the host launches the command somewhere other than the project,--agent <name>when a project has more than one agent, `--apps-dir` for a build output other than `dist/mcp-apps`, `--timeout ` and `--max-result-bytes `. --projectis what makes a plain host configuration possible. A host starts the command with a working directory of its own, and at least one desktop host ignores acwdfield entirely — so without it the only thing that worked was a shell wrapper doingcd <project> && exec .... A directory that is not a project is now refused before the bundler starts, with the flag named.The command opens no port: the Vite dev server it uses runs with its websocket off, so several Litro MCP servers run side by side. Previously the second one printed
WebSocket server error: Port 24678 is already in use. It also shuts down when its host disconnects, rather than leaving an orphaned process holding that port.Also fixes
litro mcp-app build's "not installed" detection, which missed how Vite 8 words a missing dependency ("Failed to load url ... Does the file exist?") and so told the reader "could not load", with a Vite stack, instead of naming the package to install. -
1f347da: Export
normalizePathname, the one canonicalization every route matcher shares.A Litro app has two matchers that have to agree: the client router, and the catch-all handler in
server/routes/[...].ts. They were separate implementations, and neither accepted a trailing slash — so/docs/a/matched on neither side. The failure was invisible, because an SSG build writesdocs/a/index.htmland a static host answers the trailing-slash URL with 200 and every asset. Only the client missed, and the page rendered blank.normalizePathnameis re-exported from@beatzball/litro-router, which is dependency-free and where the client router already uses it. A scaffolded app depends on@beatzball/litroalone, so its handler can now reach the same implementation:import { normalizePathname } from "@beatzball/litro"; const pathname = normalizePathname(getRequestURL(event).pathname);The built-in OG image handler canonicalizes the same way, so an OG image resolves the same route as the page it illustrates.
Patch Changes
- Updated dependencies [1f347da]
- @beatzball/litro-router@0.3.0
0.16.3
Patch Changes
-
8b5172c: Give every page a correct box model inside its shadow root.
A document stylesheet does not cross a shadow boundary, so the
box-sizing: border-boxreset every recipe ships in its global stylesheet never reached a page component.<main>, sizedwidth: 100%with horizontal padding, computed ascontent-boxand measured 438px on a 390px screen.LitroPagenow carries the reset itself:static styles = pageResetin Lit, and the FASTLitroPage.define()injects it ahead of whatever styles a page passes. Elena is unchanged — it server-renders light DOM, where the document stylesheet already applies.Upgrading fixes an existing app. A page that declares no styles of its own needs no edit at all. A page that declares
static override stylesreplaces the inherited value, so compose instead:import { LitroPage, pageReset } from '@beatzball/litro/runtime'; static override styles = [pageReset, css`...`];pageResetis exported from@beatzball/litro/runtimefor any component that cannot extendLitroPage.
0.16.2
Patch Changes
-
1348cfa: Keep a page's element registrations in the Nitro server bundle.
Nitro tells Rollup that every module is side-effect free, so a page's
import './components/litro-card.js'— the line that runscustomElements.define()— was deleted from the server bundle. The element was never registered during SSR, so the server HTML carried a bare<litro-card>tag with no shadow root and no content, and the build still exited 0.The page scanner now marks the app's own source files as side-effectful, so those imports survive. Dependencies are unchanged: they keep deciding through their own
"sideEffects"field.
0.16.1
Patch Changes
- f05c8ce:
litro mcp-app buildno longer leaves partial output when it fails. It wrote each app's.htmland.jsonas soon as that app packed, so a build that failed on a later app — one with no default export, or two apps claiming oneuri— exited 1 with the earlier apps on disk and nomanifest.json. Every app is now packed and checked first, and nothing is written unless all of them pass. A failed build leaves the output directory exactly as it was.
0.16.0
Minor Changes
-
5c09b18:
litro mcp-app buildderives each app'sui://address from its file pathThe package name is the authority and the file path is the path, so
mcp-apps/weather/card.tsin a package namedplaygroundpacks asui://playground/weather/card. Filesystem-as-routing is the convention everywhere else in Litro, and an app declaring its own address was the odd one out. An explicituriin the config still wins.The output mirrors the source tree to match, so
mcp-apps/weather/card.tswritesdist/mcp-apps/weather/card.html— 0.15.0 flattened that toweather-card.html, which let it collide with a realweather-card.ts. If you already had app files in subfolders, their output paths move;manifest.jsonentries stay relative to the output directory, so reading those needs no change.One rule with no special cases: rename the package and every address moves together, which is what an authority is for. The authority comes from the package rather than the first folder because a
ui://address needs a host AND a path — with the first folder as authority, a file sitting flat inmcp-apps/would give hostweather-cardand an empty path, a different shape from every nested file. A scoped name contributes only its last part, and a name that cannot be a uri host means every app in that project must seturiitself.Names that cannot become an address are refused — unless the app names one. For a DERIVED address, file and folder names may use letters, digits,
.,_,~and-; a space,%or a non-ASCII letter is rejected, because a parser rewrites it and the descriptor would then name a resource under one address while the host caches it under another. This also closes a silent collision:big card.tsandbig%20card.tsare two raw strings that resolve to one address. An app that sets its ownuriis exempt — the filename is only a filename then.Five refusals are NOT exemptible, because an address cannot answer them: a
.or..segment, which does not survive path normalisation and, with a leading.., writes outside the output directory; a backslash, which the glob's absolute form rewrites into/so the loader looks for a file that is not there; a#or?, which the module loader reads as url syntax and then reports the file as missing; a C0 control character or Unicode line separator, which has no printable form and would appear as itself in the manifest, the descriptor and every error message (U+007F is allowed: the line is drawn at the C0 range and DEL sits just outside it); and an app packing tomanifestat the top level, where the index would overwrite its own descriptor (matched by Unicode case folding, sinceManifest.jsonandmanifeſt.jsonare both the same file asmanifest.jsonon macOS and Windows).Problems are reported at once where they can be, before a module is loaded or a byte is written, instead of one failed build per mistake. The exception is a character that only breaks a DERIVED address: whether it matters depends on whether the app declares its own
uri, which is not known until the file loads.assertUniqueUriscompares RFC 3986 equivalence — folding host case and percent-triplet case on top of whatnew URL()does — and lists every clash rather than the first.Dynamic segments are rejected for a derived address, and exempt alongside an explicit one.
[slug],[[opt]]and[...all]mean something inpages/and nothing here.index.tsis not the folder root here either.Also: an error thrown while loading an app file is reported with the file named, instead of escaping the command as a raw stack.
0.15.0
Minor Changes
-
df9971f: Add
litro mcp-app build— packs everymcp-apps/*.tsinto a self-contained MCP Appsui://document.Each app writes
dist/mcp-apps/<name>.htmland<name>.json(theresources/*descriptor), plus amanifest.jsonlisting them all. The output is plain files, so any MCP server can serve them; nothing assumes the serving side is a Litro one.--dirand--outoverride the defaults.The build fails if two apps declare the same
ui://address: a host caches templates by URI, so a collision does not merge or warn — one app quietly serves the other's markup.Requires
@beatzball/litro-agent, which is loaded from the project at run time rather than imported (it depends on this package, so a static import would be a cycle) — a project without it gets an instruction instead of a resolver error.
0.14.0
Minor Changes
-
15c112d: Add
litro docs syncandlitro docs checkfor starlight docs sites.A starlight site has two sources of truth that can silently disagree: the Markdown files in the content directory, and the hand-written
sidebararray inserver/starlight.config.js. Add a page and forget the config and the page is live but unreachable — no link, no prev/next, and nothing says so.litro docs syncrewrites the sidebar from your pages' frontmatter, usingsidebar.order,sidebar.groupandsidebar.label.litro docs checkchanges nothing and exits 1 on drift: a page with notitleordescription, a body that opens with its own#heading (duplicating the frontmatter title), colliding slugs, a page missing from the sidebar, or a sidebar link pointing at no page. Suitable as a CI step.
This also makes the recipe's own documentation true. It has always claimed
sidebar.order"controls sort order within the sidebar group" and thatsidebar.labeloverrides the sidebar text — neither field was read by anything. Both work now, andsidebar.groupjoins them.syncrefuses to run when the sidebar has several groups but no page declares one, since that would silently collapse a hand-built navigation into a single group. It prints the group each page currently belongs to so the structure can be restored by copy-paste, and takes--forcefor a deliberate flatten.
0.13.1
Patch Changes
-
83c8d5a: Remove the
sourceexport condition. It pointed consumers at the package's TypeScript source, and Vite does not transpile TypeScript that lives insidenode_modules— so an installed app got Lit's@customElementdecorators emitted as raw syntax:(@at(`litro-outlet`) class extends rt { ... })No browser can parse that. The client bundle died with
Invalid or unexpected token, nothing hydrated, and the page rendered blank — while the build still exited 0 and the prerendered HTML was still correct.This affected any app whose
vite.config.tslisted'source'inresolve.conditions(which everycreate-litrotemplate did) on Vite 8. Vite 5 was unaffected, so apps only broke on upgrading. Four of the six recipe variants were affected: Lit and FAST apps broke on@customElement/@attr; Elena apps use no decorators and were fine.Existing apps need no code change — upgrading is enough. Leaving
'source'inresolve.conditionsis now harmless, because the condition no longer matches and resolution falls through to the compiled output. -
Updated dependencies [83c8d5a]
- @beatzball/litro-router@0.2.1
0.13.0
Minor Changes
- 141513a: Add a per-page
bodyScripthook: pages can return an optionalbodyScriptstring (raw HTML, typically a synchronous<script>) fromdefinePageData(), and the shell emits it at end-of-body immediately before the app-bundle script. This gives pages a synchronous, pre-hydration slot — symmetric withseoHeadfor<head>— for filling server-unknowable values (e.g. times in the user's local timezone) on first paint. LikeseoHead/seoTitle, the field is stripped from the serialized__litro_data__client JSON. Pages that don't use it are byte-for-byte unchanged.
Patch Changes
-
e576f80: Bump
nitropackfrom^2.13.1to^2.13.4, resolving Medium-severity advisories GHSA-5w89-w975-hf9q and GHSA-9phm-9p8f-hw5m. -
16d2705:
litro devnow serves the live client entry (/app.ts) through Vite instead of a stale pre-builtdist/client/app.js— source edits reflect in the browser without a rebuild (issue 97). The newlitroViteDevConfig()/warmupLitroViteServer()helpers (@beatzball/litro/runtime/vite-dev.js) centralise the dev Vite config: devbase: '/'so module URLs stay clear of the/_litro/static mount, dependency pre-optimization and page warmup to prevent mid-load full reloads, and watcher ignores for.nitro//.litro/so Nitro regenerating its types no longer forces a full browser reload. The actions Vite plugin now also stubs@beatzball/litro/actions/serverby resolved path, which live-source dev requires to keepnode:cryptoimports out of the browser graph.Backwards compatible for existing apps: the live entry only activates when the app's
server/middleware/vite-dev.tsbuilds its Vite server fromlitroViteDevConfig()(which setsLITRO_DEV_LIVE_ENTRY). Apps still running a previously-scaffolded middleware keep their prior dev behavior unchanged after upgrading; update the middleware to the current template to opt in to the live entry. -
Updated dependencies [16d2705]
- @beatzball/litro-router@0.2.0
0.12.0
Minor Changes
- 97e80be: Expose the NDJSON stream wire protocol (
createStreamEncoder,createStreamDecoder,serializeValue,deserializeValue,isAsyncIterable) as a public@beatzball/litro/streamsubpath so Server Actions and the agent layer share one protocol.
0.11.1
Patch Changes
- a87a760: Content layer: duplicate slugs now fail the build with an error naming the colliding files. Slugs are derived from the filename (or the parent directory for
index.md), sodocs/setup.mdandblog/setup.mdcollide — previously the slug-keyed index silently kept only one of them, dropping the other from every listing and lookup.
0.11.0
Minor Changes
-
7602471: Server Actions milestone 2: progressive-enhancement forms and streaming returns.
- Forms:
actionUrl()renders plain<form method="post">targets for actions; without JS the endpoint answers with a Post/Redirect/Get flow (one-shotlitro-form-errorcookie, read viagetFormErrors()); with JS,enhanceForms()(@beatzball/litro/actions/form-client) upgrades submits to seroval RPCs and reports results vialitro:action-success/litro:action-errorevents. Opt-incsrf: 'token'double-submit mode withcsrfToken(); form targets require adefineActioninput schema. - Streaming: action handlers may return an
AsyncIterable(async generators included); responses stream asapplication/x-ndjsonseroval cross-JSON lines andcallActionyields chunks incrementally, preserving object identity across chunks. - Follow-ups: the Origin gate honors
x-forwarded-host;.mjsaction modules keep their extension in generated manifests; new@beatzball/litro/actions/serversubpath (server-only helpers, stubbed in client builds).
Upgrading from 0.10.x or earlier: Server Actions (typed RPC, forms, and streaming together) are new in 0.11.0 and fully opt-in — upgrading the dependency changes nothing until you wire the feature, and there are no breaking changes. Adding actions to an existing app is six one-time edits, documented in the Server Actions guide's Setup section. One of them,
server/plugins/litro-actions.ts, must be committed rather than gitignored (Nitro scansserver/plugins/before the build hook that would regenerate it — an ignored copy makesactionUrl()throw on a fresh clone's first dev run). Apps scaffolded with@beatzball/create-litro0.7.0 or later come pre-wired. - Forms:
-
17a0eca: Add Server Actions (typed RPC). Export an async function from a
*.server.tsmodule and call it from anywhere: in-process during SSR, or as a typed HTTP call (POST /__litro/action/:id) from the browser — the Vite plugin rewrites client imports into generated stubs, so server code and its dependencies never enter the client bundle. IncludesdefineActionwith Standard Schema input validation, seroval JSON-mode serialization (Date/Map/Set/BigInt/circular refs round-trip), default-on CSRF protection (custom header +Sec-Fetch-Site/Originchecks), structured error forwarding viaLitroActionError, and a Nitro build plugin that scans action modules and generates the endpoint handler. New subpath exports:@beatzball/litro/actions,@beatzball/litro/actions/client,@beatzball/litro/actions/handler,@beatzball/litro/plugins/actions, pluslitroActionsPluginfrom@beatzball/litro/vite. Also fixes a latent dev-server reload loop by making generated-file writes idempotent in the page scanner.
0.10.0
Minor Changes
-
1f4d669: Upgrade Vite from 5 to 8 (Rolldown + Oxc bundler). Builds are substantially faster and the toolchain moves onto the Oxc transform pipeline. The Lit decorator transpile (
experimentalDecorators/useDefineForClassFieldsfromtsconfig.json) is honored by Oxc exactly as it was by esbuild, so client bundles are unchanged. No Litro config changes were required —build.rollupOptionsis accepted via Vite's compatibility layer.Breaking for consumers: Vite 8 requires Node
^20.19.0 || >=22.12.0(Node 18 is no longer supported). Existing projects should bump their ownvitedependency to^8and ensure they are on a supported Node version. See the Vite 8 upgrade note for details.
Patch Changes
- f0e3423: Docs accuracy: correct the published Elena 0.8.0 CHANGELOG entry to reflect that the adapter uses direct light DOM SSR (no
@elenajs/ssrdependency); fix the JSDoc onLitroConfigand the comment inplugins/pages.tsthat misdescribed adapter selection (the only working path isprocess.env.LITRO_ADAPTER, not aruntimeConfig.litro.adapterblock). - fe81671: npm metadata + dependency cleanup: rewrite the package description and keywords to reflect that all three adapters (Lit / FAST / Elena) are first-class, and drop the unused
execaruntime dependency (the CLI useschild_process.spawndirectly percli/index.ts:18). - Updated dependencies [fe81671]
- @beatzball/litro-router@0.1.9
0.9.1
Patch Changes
-
a7d2dc1: Fix: emitted
.d.tsfiles for the Elena adapter no longer reference a nonexistentElenaClasstype from@elenajs/core. Downstream consumers with strict TypeScript can now extendLitroPagewithout TS4113/TS2339 errors.The fix removes a stale ambient module declaration (
packages/framework/src/adapter/elena/env.d.ts) that was added against@elenajs/core@1.0.0-rc.13and never cleaned up after the upgrade to1.0.0. With the shim removed,LitroPage/LitroLink/LitroOutletnow extend the realElenaElementConstructorexported by@elenajs/core@1.0.0, and consumer typecheck passes.The page-manifest generator was also tightened so the generated
routes.generated.tsandserver/stubs/page-manifest.tsfiles typecheck under strict + bundlermoduleResolution: relative.jsimport specifiers replace absolute.tspaths, andpageModulesis exported asRecord<string, Record<string, unknown>>so the catch-all handler'spageModules[route.filePath]lookup no longer trips TS7053. Generated files lead with// @ts-nocheckfor any remaining generator artefacts.
0.9.0
Minor Changes
- 08cf41c: Add Portless support: CLI honours PORT env var and logs PORTLESS_URL when detected
Patch Changes
- 3a28b6b: Narrow dev-mode content polling to apps that use the content layer. The
<script>that polls/_litro/_litro-version.jsonis now only injected when the content plugin is active (signaled viaLITRO_HAS_CONTENT=true), eliminating 404 noise in dev for apps without Markdown content. Polling interval relaxed from 300ms to 2.5s. Internally,ShellOptions.devModeis renamed toShellOptions.contentDevPolling; external consumers ofbuildShell()should update the option name.
0.8.1
Patch Changes
- 97baa72: Add --host flag to dev and preview CLI commands; update @elenajs/core peer dep to stable 1.0.0
- Updated dependencies [56d6c72]
- @beatzball/litro-router@0.1.8
0.8.0
Minor Changes
- d459a96: Add FAST Element adapter with SSR, hydration, and client runtime support
- 8c081a8: Elena framework adapter — direct light DOM SSR (component classes are instantiated and stringified by the adapter; no
@elenajs/ssrdependency), progressive enhancement (no hydration), no DSD polyfill. Includes runtime components (LitroOutlet, LitroLink, LitroPage),manifestPostambleAPI for post-import component registration (currently unused by Elena, which registers via the bundledcustomElementsshim during page module imports).
Patch Changes
- 44196c4: Fix SSG plugin to support FAST adapter's customElements re-registration
- b66734f: Fix Elena adapter SSR rendering for nested custom elements and light DOM content
0.7.0
Minor Changes
- 2aa3dcf: Add framework adapter interface for pluggable web component framework support (Lit, FAST, Elena). Extract Lit-specific SSR and hydration code behind FrameworkAdapter contract. DSD polyfill is now conditional via shell options. Default adapter is 'lit' — zero breaking changes for existing projects.
0.6.0
Minor Changes
- 41136a3: Add dynamic OG image generation plugin and handler for rich link previews
0.5.1
Patch Changes
- f2f7142: Fix dev server skipping route scan when pre-built client bundle exists
0.5.0
Minor Changes
-
035912e: feat: skip links API —
skipLinksarray on ShellOptions,DEFAULT_SKIP_LINKSconstant,SkipLinktype exportfeat: SPA focus management — focus outlet after page swap, announce new page title via
aria-liveregion
Patch Changes
- 035912e: fix: include query string in SPA data fetch, defer draft filtering to query time
- Updated dependencies [035912e]
- Updated dependencies [035912e]
- @beatzball/litro-router@0.1.7
0.4.0
Minor Changes
-
8dfa849: Add shared content + UI packages and dev-mode content live reload
- Extract
docs/content/into new private workspace@beatzball/litro-docs-contentso both the SSG docs site and the upcoming SSR docs site can share the same Markdown source - Extract
docs/src/into new private workspace@beatzball/litro-docs-ui(Lit components, SEO utilities, highlight helpers) for the same reason - Add
devModeoption tobuildShell/ShellOptions: when true, injects a polling script that fetches/_litro/_litro-version.jsonevery 2.5 s and reloads the browser when the version changes - Vite content plugin (
litroContentPlugin) now writesdist/client/_litro-version.jsonon every Markdown file change and sends alitro:content-updateWebSocket event, enabling live browser reload on content edits in dev mode - Fix: add
"sideEffects": ["./src/components/*.ts"]to@beatzball/litro-docs-uiso Rollup does not tree-shake side-effect-only custom element registration imports
- Extract
-
f8b1e6d: Phase 2: docs-ssr fullstack SSR site, LitroLink styles, router scroll-to-top, content plugin production fix
- Scaffold
docs-ssr/workspace — fullstack SSR replica of the docs site using shareddocs-contentanddocs-uipackages - LitroLink: add
static override styleswith text-only inheritance (fixes double anchor point on CTA buttons) - LitroRouter: scroll to top after SPA page swap (unless hash fragment present)
- Content plugin: embed absolute path fallback for production builds where
import.meta.urlresolves incorrectly after Rollup bundling - CLI: pass
PORTenv var alongside--portflag for reliable dev server port binding - Shared components:
?hiddenattribute pattern replaces structural ternaries for SSR hydration safety;spaNavprop enables SPA navigation in SSR contexts - Blog pages: strip duplicate h1 from markdown body (title already rendered from frontmatter)
- Content negotiation:
Accept: application/jsonreturns pageData as JSON for client-side SPA data fetching - SSR preset:
ssrPreset()required in nitro.config.ts for correct production output directory
- Scaffold
Patch Changes
- Updated dependencies [f8b1e6d]
- @beatzball/litro-router@0.1.6
0.3.2
Patch Changes
-
65d309a: fix(content): add rehype-raw to content parser pipeline
HTML blocks containing blank lines (e.g. side-by-side code sections) were being split at blank line boundaries after remark's MDAST→HAST step. Adding
rehype-rawto the pipeline ensures raw HTML blocks are correctly re-parsed as a unit.
0.3.1
Patch Changes
-
f768829: fix(shell): escape
</scriptin serverDataJson to prevent early script tag terminationWhen page data contains rendered HTML (e.g. a CHANGELOG entry that mentions
</script>in a code span), the HTML parser terminates the<script type="application/json">element early at the first literal</scriptsequence. This corrupts the embedded JSON, causinggetServerData()to return null and the page to render with no server data.Fixed by replacing
</scriptwith<\/scriptin the JSON string before embedding it in the HTML shell. JSON parsers treat\/as/, so the data round-trips correctly.
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