@beatzball/create-litro 0.1.0

package/recipes/11ty-blog/template/content/blog/hello-world.md

@@ -0,0 +1,39 @@
+---
+title: Hello, World!
+date: 2026-01-15
+description: Welcome to your new Litro blog — here's what you need to know to start writing.
+tags:
+  - posts
+  - welcome
+---
+
+## Welcome to Your Litro Blog
+
+You've just scaffolded a brand-new blog powered by Litro — a fullstack web framework that combines Lit web components with Nitro's battle-tested server engine. This post is here to help you get your bearings and understand how everything fits together.
+
+Content lives in the `content/blog/` directory as plain Markdown files. Each file becomes a post. The frontmatter at the top of every file (the `---` fenced block) controls the post's title, date, description, and tags. The rest of the file is your post body, written in standard Markdown — headings, paragraphs, lists, links, code blocks, all of it.
+
+## Writing Your First Post
+
+Create a new `.md` file inside `content/blog/` and fill in the frontmatter:
+
+```markdown
+---
+title: My Second Post
+date: 2026-02-01
+description: A short summary shown on the blog listing page.
+tags:
+  - posts
+  - my-tag
+---
+
+Your post content goes here.
+```
+
+The `tags` field accepts a list. Every post in `content/blog/` automatically inherits the `posts` tag from `blog.11tydata.json`, so you only need to list additional tags in the post's own frontmatter. Tag pages are generated automatically at `/tags/<tag>` — no extra configuration required.
+
+## How Content Is Served
+
+Litro reads your Markdown files at build time (or on-demand in dev mode) using its content layer. The `getPosts()` function returns all published posts sorted newest-first, with each post's Markdown rendered to HTML in the `body` field. The `getPost(slug)` function fetches a single post by its URL slug, derived from the filename. For example, this file — `hello-world.md` — is available at `/blog/hello-world`.
+
+Run `litro dev` to start the development server and visit `http://localhost:3030` to see your blog live. Changes to content files are picked up immediately without restarting the server.

package/recipes/11ty-blog/template/litro.recipe.json

@@ -0,0 +1,7 @@
+{
+  "recipe": "11ty-blog",
+  "version": "{{recipeVersion}}",
+  "mode": "{{mode}}",
+  "contentDir": "content/blog",
+  "options": {}
+}

package/recipes/11ty-blog/template/nitro.config.ts

@@ -0,0 +1,60 @@
+import { defineNitroConfig } from 'nitropack/config';
+import type { Nitro } from 'nitropack';
+import { resolve } from 'node:path';
+import { ssrPreset, ssgPreset } from '@beatzball/litro/config';
+import pagesPlugin from '@beatzball/litro/plugins';
+import ssgPlugin from '@beatzball/litro/plugins/ssg';
+import contentPlugin from '@beatzball/litro/content/plugin';
+
+const mode = process.env.LITRO_MODE ?? 'server';
+
+export default defineNitroConfig({
+  ...(mode === 'static' ? ssgPreset() : ssrPreset()),
+
+  srcDir: 'server',
+
+  publicAssets: [
+    { dir: '../dist/client', baseURL: '/_litro/', maxAge: 31536000 },
+    { dir: '../public',      baseURL: '/',        maxAge: 0 },
+    // Serve co-located content images at their natural paths
+    { dir: '../content',     baseURL: '/content/', maxAge: 86400 },
+  ],
+
+  externals: { inline: ['@lit-labs/ssr', '@lit-labs/ssr-client'] },
+
+  esbuild: {
+    options: {
+      tsconfigRaw: {
+        compilerOptions: {
+          experimentalDecorators: true,
+          useDefineForClassFields: false,
+        },
+      },
+    },
+  },
+
+  ignore: ['**/middleware/vite-dev.ts'],
+  handlers: [
+    {
+      middleware: true,
+      handler: resolve('./server/middleware/vite-dev.ts'),
+      env: 'dev',
+    },
+  ],
+
+  hooks: {
+    'build:before': async (nitro: Nitro) => {
+      await contentPlugin(nitro);
+      await pagesPlugin(nitro);
+      await ssgPlugin(nitro);
+    },
+  },
+
+  compatibilityDate: '2025-01-01',
+
+  routeRules: {
+    '/_litro/**': {
+      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
+    },
+  },
+});

package/recipes/11ty-blog/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#litro/page-manifest": "./server/stubs/page-manifest.ts"
+  },
+  "scripts": {
+    "dev": "litro dev",
+    "build": "litro build",
+    "preview": "litro preview",
+    "generate": "litro generate"
+  },
+  "dependencies": {
+    "@beatzball/litro": "latest",
+    "lit": "^3.2.1",
+    "@lit-labs/ssr": "^3.3.0",
+    "@lit-labs/ssr-client": "^1.1.7",
+    "h3": "^1.13.0"
+  },
+  "devDependencies": {
+    "nitropack": "^2.10.4",
+    "vite": "^5.4.11",
+    "typescript": "^5.7.3"
+  }
+}

package/recipes/11ty-blog/template/pages/blog/[slug].ts

@@ -0,0 +1,65 @@
+import { html } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { customElement, state } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import { createError } from 'h3';
+import type { Post } from 'litro:content';
+import { getPost, getPosts } from 'litro:content';
+
+export interface PostData {
+  post: Post;
+}
+
+function toDate(d: Date | string): Date { return d instanceof Date ? d : new Date(d as string); }
+
+export const pageData = definePageData(async (event) => {
+  const slug = event.context.params?.slug ?? '';
+  const post = await getPost(slug);
+  if (!post) {
+    throw createError({ statusCode: 404, message: `Post not found: ${slug}` });
+  }
+  return { post } satisfies PostData;
+});
+
+export async function generateRoutes(): Promise<string[]> {
+  const posts = await getPosts();
+  return posts.map(post => post.url);
+}
+
+@customElement('page-blog-slug')
+export class BlogPostPage extends LitroPage {
+  @state() declare serverData: PostData | null;
+
+  render() {
+    const { post } = this.serverData ?? {};
+    if (!post) return html`<p>Loading…</p>`;
+    return html`
+      <article>
+        <header>
+          <h1>${post.title}</h1>
+          <time datetime="${toDate(post.date).toISOString()}">${toDate(post.date).toLocaleDateString()}</time>
+          ${post.tags.length > 0 ? html`
+            <ul class="tags">
+              ${post.tags.map(tag => html`
+                <li><a href="/tags/${tag}">#${tag}</a></li>
+              `)}
+            </ul>
+          ` : ''}
+        </header>
+        <div class="post-body">
+          <!-- unsafeHTML renders the Markdown-generated HTML directly.
+               The content directory is trusted-author-only; do not place
+               user-submitted or untrusted content here without first
+               sanitizing with a library such as rehype-sanitize. -->
+          ${unsafeHTML(post.body)}
+        </div>
+        <footer>
+          <a href="/blog">← Back to Blog</a>
+        </footer>
+      </article>
+    `;
+  }
+}
+
+export default BlogPostPage;

package/recipes/11ty-blog/template/pages/blog/index.ts

@@ -0,0 +1,43 @@
+import { html } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import type { Post } from 'litro:content';
+import { getPosts } from 'litro:content';
+
+export interface BlogIndexData {
+  posts: Post[];
+}
+
+function toDate(d: Date | string): Date { return d instanceof Date ? d : new Date(d as string); }
+
+export const pageData = definePageData(async (_event) => {
+  const posts = await getPosts();
+  return { posts } satisfies BlogIndexData;
+});
+
+@customElement('page-blog')
+export class BlogIndexPage extends LitroPage {
+  @state() declare serverData: BlogIndexData | null;
+
+  render() {
+    const { posts = [] } = this.serverData ?? {};
+    return html`
+      <main>
+        <h1>Blog</h1>
+        <ul>
+          ${posts.map(post => html`
+            <li>
+              <a href="${post.url}">${post.title}</a>
+              <time datetime="${toDate(post.date).toISOString()}">${toDate(post.date).toLocaleDateString()}</time>
+              ${post.description ? html`<p>${post.description}</p>` : ''}
+            </li>
+          `)}
+        </ul>
+        <a href="/">← Home</a>
+      </main>
+    `;
+  }
+}
+
+export default BlogIndexPage;

package/recipes/11ty-blog/template/pages/index.ts

@@ -0,0 +1,58 @@
+import { html } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import type { Post } from 'litro:content';
+import { getPosts, getGlobalData } from 'litro:content';
+
+export interface HomeData {
+  recentPosts: Post[];
+  siteTitle: string;
+  siteDescription: string;
+}
+
+function toDate(d: Date | string): Date { return d instanceof Date ? d : new Date(d as string); }
+
+export const pageData = definePageData(async (_event) => {
+  const [recentPosts, metadata] = await Promise.all([
+    getPosts({ limit: 5 }),
+    getGlobalData(),
+  ]);
+  return {
+    recentPosts,
+    siteTitle: String(metadata.title ?? '{{projectName}}'),
+    siteDescription: String(metadata.description ?? ''),
+  } satisfies HomeData;
+});
+
+@customElement('page-home')
+export class HomePage extends LitroPage {
+  @state() declare serverData: HomeData | null;
+
+  render() {
+    const { recentPosts = [], siteTitle = '{{projectName}}', siteDescription = '' } = this.serverData ?? {};
+    return html`
+      <main>
+        <header>
+          <h1>${siteTitle}</h1>
+          ${siteDescription ? html`<p>${siteDescription}</p>` : ''}
+        </header>
+        <section>
+          <h2>Recent Posts</h2>
+          <ul>
+            ${recentPosts.map(post => html`
+              <li>
+                <a href="${post.url}">${post.title}</a>
+                <time datetime="${toDate(post.date).toISOString()}">${toDate(post.date).toLocaleDateString()}</time>
+                ${post.description ? html`<p>${post.description}</p>` : ''}
+              </li>
+            `)}
+          </ul>
+          <p><a href="/blog">All Posts →</a></p>
+        </section>
+      </main>
+    `;
+  }
+}
+
+export default HomePage;

package/recipes/11ty-blog/template/pages/tags/[tag].ts

@@ -0,0 +1,53 @@
+import { html } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import type { Post } from 'litro:content';
+import { getPosts, getTags } from 'litro:content';
+
+export interface TagData {
+  tag: string;
+  posts: Post[];
+}
+
+function toDate(d: Date | string): Date { return d instanceof Date ? d : new Date(d as string); }
+
+export const pageData = definePageData(async (event) => {
+  const tag = event.context.params?.tag ?? '';
+  const posts = await getPosts({ tag });
+  return { tag, posts } satisfies TagData;
+});
+
+export async function generateRoutes(): Promise<string[]> {
+  const tags = await getTags();
+  return tags.map(tag => `/tags/${tag}`);
+}
+
+@customElement('page-tags-tag')
+export class TagPage extends LitroPage {
+  @state() declare serverData: TagData | null;
+
+  render() {
+    const { tag = '', posts = [] } = this.serverData ?? {};
+    return html`
+      <main>
+        <h1>Posts tagged: #${tag}</h1>
+        <ul>
+          ${posts.map(post => html`
+            <li>
+              <a href="${post.url}">${post.title}</a>
+              <time datetime="${toDate(post.date).toISOString()}">${toDate(post.date).toLocaleDateString()}</time>
+            </li>
+          `)}
+        </ul>
+        <p>
+          <a href="/blog">← All Posts</a>
+          &nbsp;|&nbsp;
+          <a href="/">← Home</a>
+        </p>
+      </main>
+    `;
+  }
+}
+
+export default TagPage;

package/recipes/11ty-blog/template/server/api/hello.ts

@@ -0,0 +1,6 @@
+import { defineEventHandler } from 'h3';
+
+export default defineEventHandler(() => ({
+  message: 'Hello from {{projectName}}!',
+  timestamp: new Date().toISOString(),
+}));

package/recipes/11ty-blog/template/server/api/posts.ts

@@ -0,0 +1,8 @@
+import { defineEventHandler, getQuery } from 'h3';
+import { getPosts } from 'litro:content';
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event);
+  const tag = typeof query.tag === 'string' ? query.tag : undefined;
+  return getPosts({ tag });
+});

package/recipes/11ty-blog/template/server/middleware/vite-dev.ts

@@ -0,0 +1,29 @@
+import { defineEventHandler, fromNodeMiddleware } from 'h3';
+
+let viteHandlerPromise: Promise<ReturnType<typeof fromNodeMiddleware>> | null = null;
+
+export default defineEventHandler(async (event) => {
+  if (!process.dev || !process.env.NITRO_DEV_WORKER_ID) return;
+
+  if (!viteHandlerPromise) {
+    const httpServer = (event.node.req.socket as import('node:net').Socket & {
+      server?: import('node:http').Server;
+    }).server;
+
+    viteHandlerPromise = import('vite')
+      .then(({ createServer }) =>
+        createServer({
+          server: {
+            middlewareMode: true,
+            hmr: httpServer ? { server: httpServer } : true,
+          },
+          appType: 'custom',
+          root: process.cwd(),
+        }),
+      )
+      .then((server) => fromNodeMiddleware(server.middlewares));
+  }
+
+  const viteHandler = await viteHandlerPromise;
+  return viteHandler(event);
+});

package/recipes/11ty-blog/template/server/routes/[...].ts

@@ -0,0 +1,55 @@
+import { defineEventHandler, setResponseHeader, getRequestURL } from 'h3';
+import { createPageHandler } from '@beatzball/litro/runtime/create-page-handler.js';
+import type { LitroRoute } from '@beatzball/litro';
+import { routes, pageModules } from '#litro/page-manifest';
+
+function matchRoute(
+  pathname: string,
+): { route: LitroRoute; params: Record<string, string> } | undefined {
+  for (const route of routes) {
+    if (route.isCatchAll) return { route, params: {} };
+
+    if (!route.isDynamic) {
+      if (pathname === route.path) return { route, params: {} };
+      continue;
+    }
+
+    const regexStr =
+      '^' +
+      route.path
+        .replace(/:([^/]+)\(\.\*\)\*/g, '(?<$1>.+)')
+        .replace(/:([^/?]+)\?/g, '(?<$1>[^/]*)?')
+        .replace(/:([^/]+)/g, '(?<$1>[^/]+)') +
+      '$';
+
+    try {
+      const match = pathname.match(new RegExp(regexStr));
+      if (match) return { route, params: (match.groups ?? {}) as Record<string, string> };
+    } catch {
+      // malformed pattern — skip
+    }
+  }
+  return undefined;
+}
+
+export default defineEventHandler(async (event) => {
+  const pathname = getRequestURL(event).pathname;
+  const result = matchRoute(pathname);
+
+  if (!result) {
+    setResponseHeader(event, 'content-type', 'text/html; charset=utf-8');
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8" /><title>404</title></head>
+<body><h1>404 — Not Found</h1><p>No page matched <code>${pathname}</code>.</p></body>
+</html>`;
+  }
+
+  const { route: matched, params } = result;
+  event.context.params = { ...event.context.params, ...params };
+
+  const handler = createPageHandler({
+    route: matched,
+    pageModule: pageModules[matched.filePath],
+  });
+  return handler(event);
+});

package/recipes/11ty-blog/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", ".nitro"]
+}

package/recipes/11ty-blog/template/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import litroContentPlugin from '@beatzball/litro/vite';
+
+export default defineConfig({
+  plugins: [litroContentPlugin()],
+  base: '/_litro/',
+  resolve: {
+    conditions: ['source', 'browser', 'module', 'import', 'default'],
+  },
+  build: {
+    outDir: 'dist/client',
+    rollupOptions: {
+      input: 'app.ts',
+      output: {
+        entryFileNames: '[name].js',
+      },
+    },
+  },
+});

package/recipes/fullstack/recipe.config.ts

@@ -0,0 +1,10 @@
+import type { LitroRecipe } from '../../src/types.js';
+
+const recipe: LitroRecipe = {
+  name: 'fullstack',
+  displayName: 'Fullstack App',
+  description: 'Full-stack Lit + Nitro app with SSR and blog example pages',
+  mode: 'both',
+};
+
+export default recipe;

package/recipes/fullstack/template/app.ts

@@ -0,0 +1,20 @@
+// CRITICAL: must be first — patches LitElement before any component is loaded.
+import '@lit-labs/ssr-client/lit-element-hydrate-support.js';
+
+// Client runtime: router outlet and link custom elements.
+import 'litro/runtime/LitroOutlet.js';
+import 'litro/runtime/LitroLink.js';
+
+// Routes generated by the page scanner before each vite build.
+// routes.generated.ts lives at the project root (not in dist/) so Vite's
+// emptyOutDir does not delete it between builds.
+import { routes } from './routes.generated.js';
+
+document.addEventListener('DOMContentLoaded', () => {
+  const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
+  if (outlet) {
+    outlet.routes = routes;
+  } else {
+    console.warn('[litro] <litro-outlet> not found — router will not start.');
+  }
+});

package/recipes/fullstack/template/nitro.config.ts

@@ -0,0 +1,67 @@
+import { defineNitroConfig } from 'nitropack/config';
+import type { Nitro } from 'nitropack';
+import { resolve } from 'node:path';
+import { ssrPreset, ssgPreset } from '@beatzball/litro/config';
+import pagesPlugin from '@beatzball/litro/plugins';
+import ssgPlugin from '@beatzball/litro/plugins/ssg';
+
+// LITRO_MODE controls the deployment target at build time:
+//   LITRO_MODE=server  litro build     (default — Node.js server)
+//   LITRO_MODE=static  litro generate  (SSG — static HTML for CDN)
+const mode = process.env.LITRO_MODE ?? 'server';
+
+export default defineNitroConfig({
+  ...(mode === 'static' ? ssgPreset() : ssrPreset()),
+
+  // Nitro auto-discovers server/routes/, server/api/, server/middleware/
+  srcDir: 'server',
+
+  // publicAssets.dir is resolved relative to srcDir ('server/').
+  // Use '../dist/client' (not 'dist/client') to reach <rootDir>/dist/client.
+  publicAssets: [
+    { dir: '../dist/client', baseURL: '/_litro/', maxAge: 31536000 },
+    { dir: '../public',      baseURL: '/',        maxAge: 0 },
+  ],
+
+  // Must be bundled for edge runtimes (Cloudflare Workers, Vercel Edge).
+  externals: { inline: ['@lit-labs/ssr', '@lit-labs/ssr-client'] },
+
+  // Lit uses legacy experimental decorators.
+  esbuild: {
+    options: {
+      tsconfigRaw: {
+        compilerOptions: {
+          experimentalDecorators: true,
+          useDefineForClassFields: false,
+        },
+      },
+    },
+  },
+
+  // Exclude vite-dev.ts from auto-discovery so import('vite') never enters
+  // the production module graph. Re-register with env:'dev' so it only runs
+  // during development.
+  ignore: ['**/middleware/vite-dev.ts'],
+  handlers: [
+    {
+      middleware: true,
+      handler: resolve('./server/middleware/vite-dev.ts'),
+      env: 'dev',
+    },
+  ],
+
+  hooks: {
+    'build:before': async (nitro: Nitro) => {
+      await pagesPlugin(nitro);
+      await ssgPlugin(nitro);
+    },
+  },
+
+  compatibilityDate: '2025-01-01',
+
+  routeRules: {
+    '/_litro/**': {
+      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
+    },
+  },
+});

package/recipes/fullstack/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#litro/page-manifest": "./server/stubs/page-manifest.ts"
+  },
+  "scripts": {
+    "dev": "litro dev",
+    "build": "litro build",
+    "preview": "litro preview",
+    "generate": "litro generate"
+  },
+  "dependencies": {
+    "@beatzball/litro": "latest",
+    "lit": "^3.2.1",
+    "@lit-labs/ssr": "^3.3.0",
+    "@lit-labs/ssr-client": "^1.1.7",
+    "h3": "^1.13.0"
+  },
+  "devDependencies": {
+    "nitropack": "^2.10.4",
+    "vite": "^5.4.11",
+    "typescript": "^5.7.3"
+  }
+}

package/recipes/fullstack/template/pages/blog/[slug].ts

@@ -0,0 +1,43 @@
+import { LitElement, html } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import { definePageData } from '@beatzball/litro';
+
+export interface PostData {
+  slug: string;
+  title: string;
+  content: string;
+}
+
+// Runs on the server; event.context.params contains the matched route params.
+export const pageData = definePageData(async (event) => {
+  const slug = event.context.params?.slug ?? '';
+  return {
+    slug,
+    title: `Post: ${slug}`,
+    content: `This is the content for the "${slug}" post.`,
+  } satisfies PostData;
+});
+
+// Tells the SSG which concrete paths to prerender when LITRO_MODE=static.
+export async function generateRoutes(): Promise<string[]> {
+  return ['/blog/hello-world', '/blog/getting-started', '/blog/about-litro'];
+}
+
+@customElement('page-blog-slug')
+export class BlogPostPage extends LitElement {
+  @state() declare serverData: PostData | null;
+
+  render() {
+    return html`
+      <article>
+        <h1>${this.serverData?.title ?? 'Loading…'}</h1>
+        <p>${this.serverData?.content ?? ''}</p>
+        <litro-link href="/blog">← Back to Blog</litro-link>
+        &nbsp;|&nbsp;
+        <litro-link href="/">← Home</litro-link>
+      </article>
+    `;
+  }
+}
+
+export default BlogPostPage;