Litro
Create a new Litro app
npm install @beatzball/create-litro pnpm add @beatzball/create-litro
Scaffold a new Litro app.
Usage
npm create @beatzball/litro@latest my-app
# or
pnpm create @beatzball/litro my-app
# or
yarn create @beatzball/litro my-app
Follow the interactive prompts to choose a recipe and rendering mode, or pass flags directly to skip them:
# Fullstack SSR app (default)
npm create @beatzball/litro@latest my-app --recipe fullstack --mode ssr
# 11ty-compatible blog (SSG or SSR)
npm create @beatzball/litro@latest my-app --recipe 11ty-blog --mode ssg
# List all available recipes
npm create @beatzball/litro@latest -- --list-recipes
Recipes
fullstack (default)
A fullstack Lit + Nitro app with file-based routing and server-side rendering.
Generated app includes:
pages/index.ts— home page withdefinePageData()server fetchingpages/blog/index.ts— blog listing pagepages/blog/[slug].ts— dynamic post page withgenerateRoutes()for SSGserver/api/hello.ts— JSON API endpoint- Config files:
nitro.config.ts,vite.config.ts,tsconfig.json
11ty-blog
A Markdown blog using the litro:content content layer, compatible with the 11ty data cascade format (frontmatter, .11tydata.json directory data, _data/metadata.js global data). Supports both SSR (dev server) and SSG (prerender to static HTML).
Generated app includes:
content/blog/— Markdown posts with YAML frontmattercontent/_data/metadata.js— global site metadatapages/index.ts— home page showing recent postspages/blog/index.ts— post listing with all postspages/blog/[slug].ts— individual post page withgenerateRoutes()pages/tags/[tag].ts— tag-filtered post listingserver/api/posts.ts— JSON API for posts (optional?tag=filter)litro.recipe.json— written to the project root so the content plugin knows where to find posts
After scaffolding
cd my-app
pnpm install
pnpm dev # start dev server on http://localhost:3030
For static site generation:
LITRO_MODE=static pnpm build # prerenders all routes to HTML
The litro:content virtual module
The 11ty-blog recipe uses litro:content, a virtual module provided by the Litro framework:
import { getPosts, getPost, getTags, getGlobalData } from 'litro:content';
// In a page file:
const posts = await getPosts({ tag: 'tutorial', limit: 5 });
const post = await getPost('hello-world');
const tags = await getTags();
const meta = await getGlobalData(); // reads _data/metadata.js
The content layer reads Markdown files from the directory specified in litro.recipe.json (contentDir). Posts are sorted by date descending. Draft posts (frontmatter draft: true) are excluded by default.
Add /// <reference types="litro/content/env" /> (or the equivalent tsconfig.json entry) for TypeScript type support.
License
Apache License 2.0 — Copyright 2026 beatzball.
Changelog
0.3.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
0.2.1
Patch Changes
- 338e2c7: Add Playwright e2e setup to all recipe templates. Each scaffolded project now includes
playwright.config.tsande2e/index.spec.tswith 3 starter tests, and@playwright/testindevDependencies.
0.2.0
Minor Changes
-
78fdaf6: Add
starlightrecipe — Astro Starlight-inspired docs + blog site scaffolded as Lit web components with full SSG support.npm create @beatzball/litro my-docs -- --recipe starlightscaffolds a static docs + blog site with:- Layout components:
<starlight-page>,<starlight-header>,<starlight-sidebar>,<starlight-toc> - UI components:
<sl-card>,<sl-card-grid>,<sl-badge>,<sl-aside>,<sl-tabs>,<sl-tab-item> - Pages:
/(splash),/docs/:slug,/blog,/blog/:slug,/blog/tags/:tag— all SSG-prerendered --sl-*CSS token layer with dark/light mode toggle and no flash of unstyled contentserver/starlight.config.js— site title, nav links, sidebar groups- SSG-only (no
--modeflag needed)
- Layout components:
0.1.4
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.
0.1.3
Patch Changes
-
bfd8f9a: Fix fullstack recipe: add
base: '/_litro/'tovite.config.tsand extendLitroPagein[slug].tsWithout
base: '/_litro/', Vite's compiled modulepreload URL resolver emits paths like/assets/chunk.jsinstead of/_litro/assets/chunk.js. These requests hit the Nitro catch-all page handler and return HTML, causing a MIME type error that leaves dynamic routes (e.g./blog/hello-world) stuck on "Loading…".Also fixes
pages/blog/[slug].tsto extendLitroPage(notLitElement) and implementfetchData(), so client-side SPA navigation to different slugs correctly updatesserverData.
0.1.2
Patch Changes
- 19f4909: Fix recipe templates using unscoped
litro/runtime/...imports instead of@beatzball/litro/runtime/..., and bumpnitropackdevDependency to^2.13.1.
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.
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.
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.