Litro
Every Litro guide in one place — getting started, core concepts, adapters, recipes, deployment and package references.
Getting Started
- Introduction Litro is a fullstack web framework combining Lit web components, Nitro server, and Vite for an integrated SSR and static generation experience.
- Getting Started Create a new Litro project in minutes using the create-litro scaffolding CLI.
- Configuration Configure your Litro project via nitro.config.ts and vite.config.ts. Adapter selection via the LITRO_ADAPTER env var (set in the shell or at the top of nitro.config.ts) or the --adapter CLI flag at scaffolding time.
- Upgrading How to upgrade an existing Litro app, and the release-by-release notes for anything that needs a decision — including opting in to the live dev entry (issue 97) introduced alongside @beatzball/litro 0.12.1.
- Known Gaps What Litro does not do yet — the missing capabilities, what each one costs you, and the workaround where one exists.
Core Concepts
- Routing Litro uses file-system routing — page filenames map directly to URL paths.
- SSR Litro uses @lit-labs/ssr with Declarative Shadow DOM for spec-compliant streaming SSR.
- Data Fetching Use definePageData for server-side data fetching and getServerData to read it on the client.
- Client Router LitroRouter is Litro's built-in client router using the native URLPattern API. No external dependency.
Features
- API Routes Create API endpoints in server/api/ using standard Nitro/H3 handlers.
- Server Actions Call server-side functions from your components over a typed RPC without writing API routes.
- Agents Build filesystem-first agents whose tools return server-rendered web components — the model reasons over data, humans see components.
- MCP Apps Package a Litro component as an MCP Apps ui:// resource — one self-contained document that paints a real, styled shell before any data arrives.
- MCP Server Serve a Litro agent's tools, and the ui:// documents it renders into, to any MCP host — over stdio with one command, or over HTTP as a Nitro route.
- Content Layer The litro:content virtual module provides a Markdown content API compatible with 11ty data files.
- Static Generation Use ssgPreset() in nitro.config.ts to prerender all routes to static HTML files.
- OG Images Generate dynamic Open Graph images for rich link previews in chat apps and social media.
- LitroRouter API reference for the built-in LitroRouter client-side router.
Adapters
- Overview Litro supports Lit and FAST Element through a pluggable adapter system. A third adapter, Elena, is deprecated and removed in v1.
- Lit The default Litro adapter. Build pages with LitElement, Shadow DOM, and @lit-labs/ssr for streaming Declarative Shadow DOM SSR.
- FAST Element Build Litro pages with Microsoft FAST Element 2 — Shadow DOM, observable-based reactivity, and @microsoft/fast-ssr for Declarative Shadow DOM SSR.
- ElenaJS The Elena adapter is deprecated and will be removed in Litro v1. Existing projects keep working; new projects should choose Lit or FAST Element.
- Switching Adapters Step-by-step guide for migrating an existing Litro project from one framework adapter to another.
Recipes
- Fullstack App The fullstack recipe creates an SSR app with API routes, a homepage, and a blog.
- 11ty Blog The 11ty-blog recipe creates a Markdown blog with the litro:content layer.
- Starlight Docs The starlight recipe creates a documentation site with sidebar navigation, TOC, and blog.
- Supernova The supernova recipe creates a product landing page in front of a starlight docs site, with an optional blog.
Deployment
- GitHub Pages Deploy your Litro SSG site to GitHub Pages using GitHub Actions.
- Coolify Deploy your Litro site to Coolify using static site build pack or Docker.
Packages
Migrate
- From Next.js A practical guide to migrating a Next.js application to Litro. Covers file-based routing, server-side data fetching, API routes, navigation, and CSS scoping with step-by-step before/after code examples.
- From Nuxt.js A practical guide to migrating a Nuxt.js application to Litro. Both frameworks share the same Nitro server engine — migration is primarily replacing Vue SFCs with Lit class components. H3 API routes copy verbatim.
- From React (to Lit) A practical guide to migrating React components to Lit web components. Covers state, lifecycle, props, slots, context, CSS scoping, and the mental model shift from function components to class components.
- From React (to FAST) A practical guide to migrating React components to FAST Element web components. Covers state, lifecycle, templates, observables, and the mental model shift from hooks to FAST's observable system.
- From React (to ElenaJS) Migrating React components to ElenaJS. The Elena adapter is deprecated and removed in Litro v1 — start a new migration on Lit or FAST instead.
Contributing
- Contributing How to contribute to Litro — running tests, submitting PRs, and the release workflow.