Coming from Astro

This page maps Astro 7 to Lumiose's current API. The linked pages have the full rules.

#Mental model

The same page model. As in Astro, pages render to HTML at build time or per request, and a page ships no JavaScript until something on it needs some. A client:* directive at the usage site makes one component instance an island, with Astro's directive names. File routes, layouts, endpoints, middleware, Markdown imports and deploy adapters all have a counterpart below.

One component model instead of two. In Astro, .astro components render on the server only, and anything interactive is written in React, Preact, Svelte, Vue or Solid. Moving a piece of UI from one side to the other means rewriting it. In Lumiose every component is TSX, in a .stsx file (TSX plus <style> blocks) or a .tsx file, set up once and updated by signals:

• The same component works on both sides. It renders as static HTML on one page and as an island on another (<Search client:idle />), with no rewrite.
• Islands can await data. An island may await data like a server component. The values are recorded while rendering on the server and replayed during hydration.
• Islands share state without a store library. They share it through defineState, seeded on the server, instead of Nano Stores.
• A route can become an SPA. Set it to spa and it gets client navigation with persistent layouts, using the same components (Rendering modes).

Typed client scripts. Astro bundles <script> tags as TypeScript, but server values only reach them through define:vars (which makes the script inline and untyped) or data-* attributes read by hand. In Lumiose, a component imports a browser script with ?client, and only the pages that render that component load it, without the island runtime. Server data goes through the attributes of a custom element whose props are typed in JSX (the example shows both).

Styles live in the component file, as in Astro, with raw CSS in <style> blocks. They are scoped by where the block is placed: at the top level of the file, or nested inside an element to scope one subtree (Styles).

Where Astro is ahead today. Be clear about these before you switch:

• Islands in React, Vue or Svelte, or several frameworks on one page. Lumiose has one component model and no React interop (When not to use Lumiose).
• The integrations ecosystem. astro add installs sitemaps, RSS, MDX, image services and CMS loaders. In Lumiose a sitemap or an RSS feed is a short route.ts endpoint you write, and some pieces have no counterpart yet (see What has no equivalent).
• Content collections and <Image>. Lumiose imports Markdown as components with validated frontmatter, but it has no collections API or image pipeline.
• Requests for small scripts. Astro inlines a small <script> into the HTML. A ?client script is a module file of its own, so a page with a few of them makes a few more requests. A Lumiose page with an island also loads the island runtime, about 10 kB gzip: use ?client for small scripts and keep islands for reactive UI.
• Maturity. Astro is past 1.0, with a team behind it. Lumiose is 0.x, with one maintainer (Stability).

What a real port showed. The author's Astro site, itsjavi.com, was ported to Lumiose 0.5.0 with the same URLs and look, its small scripts as ?client custom elements, and measured on 2026-10-21:

• JavaScript per page was 1.7-2.4 kB gzip, against 1.3-1.7 kB for Astro's inline scripts, and every page but the code editor was lighter in total, with 2 to 4 more requests.
• Type checking took 1.2 s with lumiose check, against 5.8 s with astro check.
• A fresh install had 175 packages, against 433.
• Per-page CSS was 30-50% smaller than the site's Tailwind build.
• Builds were on par (4.7 s cold, 2.2 s warm, against 4.3 s and 2.3 s); the dev server's first start was slower (4.7 s against 2.0 s).

#From Astro to Lumiose

#Components and templates

#Styles and scripts

#Islands

#Routing and pages

#Server, endpoints and actions

#Content

#Config, CLI and deploy

#What has no equivalent

#Example

A header with a search box as a React island, a theme toggle in a bundled <script>, and scoped styles, in Astro:

---
// src/components/Header.astro
import Search from "./Search.tsx"; // React, only for this island
const { title } = Astro.props;
---
<header>
  <a href="/">{title}</a>
  <Search client:idle placeholder="Search posts" />
  <button type="button" data-theme-toggle data-storage-key="theme">Theme</button>
</header>

<script>
  const button = document.querySelector<HTMLButtonElement>("[data-theme-toggle]")!;
  const key = button.dataset.storageKey!; // untyped: a typo here is a runtime bug
  button.addEventListener("click", () => {
    const dark = document.documentElement.classList.toggle("dark");
    localStorage.setItem(key, dark ? "dark" : "light");
  });
</script>

<style>
  header { display: flex; gap: 1rem; align-items: center; }
</style>

In Lumiose, the search box is a Lumiose component, which could render without a directive on another page. The theme toggle is a typed browser script that only the pages rendering the header load. Its data goes through a typed attribute:

// src/components/theme-toggle.ts: runs in the browser only
customElements.define(
  "theme-toggle",
  class extends HTMLElement {
    connectedCallback(): void {
      const key = this.getAttribute("storage-key") ?? "theme";
      this.addEventListener("click", () => {
        const dark = document.documentElement.classList.toggle("dark");
        localStorage.setItem(key, dark ? "dark" : "light");
      });
    }
  },
);

// src/components/Search.stsx
import { signal } from "lumiose";

export function Search({ placeholder }: { placeholder: string }) {
  const query = signal("");
  return (
    <form role="search" action="/search">
      <input name="q" placeholder={placeholder} bind:value={query} />
      {query() && <p>Press Enter to search for "{query()}".</p>}
    </form>
  );
}

// src/components/Header.stsx
import { Search } from "./Search.stsx";
import defineThemeToggle from "./theme-toggle.ts?client";

declare module "lumiose/jsx-runtime" {
  namespace JSX {
    interface IntrinsicElements {
      // The server side is type-checked; the script reads the attribute with getAttribute().
      "theme-toggle": JSX.HTMLProps<HTMLElement> & { "storage-key"?: string };
    }
  }
}

export function Header({ title }: { title: string }) {
  defineThemeToggle();
  return (
    <header>
      <a href="/">{title}</a>
      <Search client:idle placeholder="Search posts" />
      <theme-toggle storage-key="theme">
        <button type="button">Theme</button>
      </theme-toggle>
    </header>
  );
}

<style>
  header { display: flex; gap: 1rem; align-items: center; }
</style>

A blog post page built from a collection, in Astro:

---
// src/pages/blog/[slug].astro
import { getCollection, render } from "astro:content";
import Layout from "../../layouts/Layout.astro";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---
<Layout title={post.data.title}>
  <article><Content /></article>
</Layout>

In Lumiose, the Markdown files are imported as components. staticPaths() lists the slugs, and the page looks its post up from params. src/routes/layout.stsx wraps it without an import:

// src/routes/blog/[slug]/page.stsx
import type { Frontmatter } from "*.md";
import { Title, notFound, type PageProps } from "lumiose";

type Post = { default: () => JSX.Element; frontmatter: Frontmatter };
const modules = import.meta.glob<Post>("../../../posts/*.md", { eager: true });
const posts = new Map(
  Object.entries(modules).map(([path, post]) => [path.split("/").pop()!.replace(/\.md$/, ""), post]),
);

export function staticPaths() {
  return [...posts.keys()].map((slug) => ({ params: { slug } }));
}

export default function BlogPost({ params }: PageProps<"/blog/[slug]">) {
  const { default: Content, frontmatter } = posts.get(params.slug) ?? notFound();
  return (
    <article>
      <Title>{frontmatter.title}</Title>
      <Content />
    </article>
  );
}

#Common mistakes

• Writing frontmatter. There is no --- fence: imports go at the top of the module, and setup code goes in the component's body.
• [...slug] for an optional catch-all. It matches one or more segments in Lumiose. Astro's [...slug] is [[...slug]].
• Importing a layout into every page. A layout.stsx in the folder wraps its pages already, so importing it as well renders it twice.
• An interactive component without client:*. It renders on the server, and its handlers never run. Add a directive at the usage site, or make the route spa.
• A <script> tag for a component's behaviour. A JSX <script> is written into the HTML as is, untyped and unbundled. Import a .ts file with ?client instead.
• Passing props through staticPaths(). It returns params only; load the data in the page.
• Astro.redirect() habits. redirect() throws, so code after it does not run, and request APIs such as cookies() need a server page (LUM5001).
• Expecting page context inside an island. Islands start a new root, so context provided by the page does not reach them (LUM4010). Pass a prop, or use defineState.

#Related

• Islands and Rendering modes: what ships to the browser, and how Lumiose islands compare with Astro's.
• Components and JSX: setup once, props, children and the compiled template.
• Styles: <style> blocks scoped by placement, and $name values.
• Content: Markdown and HTML imports, frontmatter and headings.
• Web components: typed custom elements, the home of typed ?client scripts.
• Routing, Server and Data and actions: pages, middleware, endpoints and form actions.
• When not to use Lumiose: the cases where another stack fits better.