create-litro

Scaffold a new Litro app.

Usage

# 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 create npm:@beatzball/litro@latest -- my-app

Follow the interactive prompts to choose a recipe, rendering mode, and framework adapter, or pass flags directly to skip them:

# Fullstack SSR app with Lit (default)
npm create @beatzball/litro@latest my-app -- --recipe fullstack --mode ssr

# Fullstack SSR app with FAST Element
npm create @beatzball/litro@latest my-app -- --recipe fullstack --mode ssr --adapter fast

# Fullstack SSR app with Elena (light DOM)
npm create @beatzball/litro@latest my-app -- --recipe fullstack --mode ssr --adapter elena

# Starlight docs + blog, static output
npm create @beatzball/litro@latest my-docs -- --recipe starlight

# List all available recipes
npm create @beatzball/litro@latest -- --list-recipes

--adapter flag

Choose the web component framework for your project:

| Value | Framework | DOM Model | SSR | |---|---|---|---| | lit (default) | Lit 3 | Shadow DOM | Declarative Shadow DOM | | fast | FAST Element 2 | Shadow DOM | Declarative Shadow DOM | | elena | Elena | Light DOM | Direct rendering |

Omitting --adapter defaults to lit. The interactive wizard also prompts for adapter selection.

Recipes

fullstack (default)

A fullstack Lit + Nitro app with file-based routing and server-side rendering.

Generated app includes:

• pages/index.ts — home page with definePageData() server fetching
• pages/blog/index.ts — blog listing page
• pages/blog/[slug].ts — dynamic post page with generateRoutes() for SSG
• server/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 frontmatter
• content/_data/metadata.js — global site metadata
• pages/index.ts — home page showing recent posts
• pages/blog/index.ts — post listing with all posts
• pages/blog/[slug].ts — individual post page with generateRoutes()
• pages/tags/[tag].ts — tag-filtered post listing
• server/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

starlight

An Astro Starlight-inspired docs + blog site. SSG-only (no --mode flag needed).

Generated app includes:

• content/docs/*.md — documentation pages with sidebar ordering frontmatter
• content/blog/*.md — blog posts with title, date, tags, description
• Layout components: <starlight-page>, <starlight-header>, <starlight-sidebar>, <starlight-toc>
• UI components: <litro-card>, <litro-card-grid>, <litro-badge>, <litro-aside>, <litro-tabs>
• Shoelace web components available (<sl-*> names reserved for Shoelace; Litro's own primitives use litro-*)
• server/starlight.config.js — site title, nav links, sidebar groups
• public/styles/starlight.css — full --sl-* CSS token layer with dark/light mode
• Syntax highlighting via highlight.js (fire theme, applied at SSG build time)

After scaffolding

cd my-app
pnpm install
pnpm dev      # start dev server on http://localhost:3030
pnpm build    # production build
pnpm preview  # preview the production build

For static site generation (SSG):

LITRO_MODE=static pnpm build   # prerenders all routes to HTML → dist/static/

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.