Lumiose docs

Feels like React. Runs like vanilla JS. Components live in .stsx files (TSX plus raw-CSS <style> blocks), are set up once and update through signals, and every route picks its rendering mode: static, server, islands or SPA.

These docs ship inside the package, so they always match the installed version. Read them from node_modules/lumiose/docs, or from the terminal:

lumiose docs                    # this index
lumiose docs signals            # a topic, by name or path (concepts/signals)
lumiose docs "bind:value"       # search, when no topic matches
lumiose explain LUM2001         # the long-form explanation of a diagnostic
lumiose docs signals --format json

Every concept page has the same sections, in order: Concept, API, Example, Common mistakes and Related diagnostics. Reference pages list every export with its signature.

#Start here

• Getting started: Create a project, configure TypeScript and Vite, and render a first component.
• Coming from React: Hooks mapped to signals, what goes away (the rules of hooks, dependency arrays, stale closures, memoization) and the mistakes React habits cause.

#Concepts

• Components: Setup-once function components, props, children, refs and the .stsx/.tsx/.ts file types.
• Signals and reactivity: signal, computed, effect, store, owners, context and scheduling.
• Sharing state: Component, context and module-scope state; recipes for stores with actions, families, persisted signals, external stores and state shared by islands.
• JSX: Bindings, compiled idioms (.map, ternaries), class, style, events, bind:, attach and ref.
• Styles: Raw-CSS <style> blocks scoped by placement, <style global>, JS values in styles ($name), build-time math and runtime values.
• Async components: async components on server and client, <Suspense>, <ErrorBoundary>, re-runs and in-flight state.
• Islands: client:* directives, serializable props, slots and server-only boundaries.
• Routing: File routes, layouts, params, typed href(), error pages and the SPA router.
• Internationalization: Locale prefixes, per-page locale declarations, locale(), locale-aware href(), hreflang and canonical links, detection on entry.
• Data and actions: Read data with async components, serve endpoints, mutate with form actions and submit().
• Server: Request context, middleware, cookies, env, redirects and error helpers.
• Rendering modes: static, server and spa routes: choosing a mode, combining modes, islands and <Suspense>, patterns close to partial prerendering, a comparison with Astro islands, prerendered SPA pages, shell-first streaming, hydration and the build.
• SVG imports: import Icon from "./icon.svg?component" as an inline, optimised component, from your project or a package; title, currentColor, and Vite's own .svg imports.
• Markdown and HTML imports: .md and .html files as static components; GFM, heading ids, frontmatter and its hook, scoped <style>, client <script>.
• Head and document: <Title>, <Meta>, <Head> and a custom document.stsx.
• Compiler and diagnostics: What the compiler does with .stsx/.tsx, and how LUMxxxx diagnostics work.
• Testing: Test components with Vitest and the Lumiose Vite plugin.
• Security: A strict Content Security Policy with nonces and hashes (lumiose({ csp: "strict" }), cspNonce()), and the cross-site form check.

#Guides

• Authentication with Better Auth: Email and password accounts with Better Auth and Prisma: the handler as an endpoint, the session in middleware, protected pages, form actions and the browser client in an island.
• Icons with Lucide: Lucide's SVG files (lucide-static), or any SVG icon set, as inline components through ?component imports: install, size, colour and stroke with CSS, labels, and why not lucide-react.
• i18n with Paraglide JS and i18next: Messages in server pages and islands with Paraglide JS (compile-time) or i18next (a t per request), keyed by locale(); a language switcher on alternates() that updates the detection cookie; hreflang, canonical and site for search engines.
• Realtime: Server-sent events from an endpoint to an island's EventSource, WebSockets with ws on the Node adapter's server, proxy configs and per-platform notes.

#Deploy

• Overview: What lumiose build writes, the production settings (PORT, HOST, ORIGIN, LUMIOSE_SECRET) and how far each target's guide was verified.
• Docker: A multi-stage Dockerfile: node:24-alpine, production dependencies only, a non-root user and a health check.
• VPS: @lumiose/adapter-node under systemd or pm2, behind Caddy or nginx; what the adapter already does for compression and caching.
• Coolify: Deploy from the Dockerfile with Coolify's Dockerfile build pack.
• Cloudflare Workers: @lumiose/adapter-cloudflare: the Worker, static assets, bindings as ctx.platform.env.
• Vercel: @lumiose/adapter-vercel: the Build Output API, with a Node.js or Edge function.
• Netlify: @lumiose/adapter-netlify: the site and a Netlify Function.
• Bun: bun dist/server/entry.js, static files included.
• Deno: deno serve dist/server/entry.js, static files included.
• Fly.io: The Docker image on Fly Machines, behind Fly's proxy.
• Render: A Node web service (or the Docker image), and static sites.
• Railway: The Node adapter with Railway's Node builder, or the Docker image.
• Static hosts: A fully prerendered site on Cloudflare, Netlify, GitHub Pages, S3 with CloudFront or any file server.
• AWS Lambda: A handler from Lambda's events to the server build's fetch.

#Reference

• lumiose: reactivity: signal, computed, effect, batch, flush, untrack, store, owners, context (createContext, useContext), useId, getAbortSignal, isPending, isBusy, resource.
• lumiose: components: Suspense, ErrorBoundary, Portal, Dynamic, ref, Head, Title, Meta, ViewTransition, viewTransition.
• lumiose: app layer: fetchJSON, submit, isSubmitting, actionData, invalidate, fail, redirect, notFound, error, href, request APIs and types.
• lumiose: server rendering: renderToStream, renderToString and the lumiose/server subpath.
• lumiose/dom: render, the compiler-runtime contract, hydrate (lumiose/dom/hydrate) and the island loader (lumiose/dom/loader).
• lumiose/router: The SPA router: Link, navigate, isNavigating, searchParams and reactive route state.
• @lumiose/vite: The Vite plugin and its options.
• JSX types and tsconfig: lumiose/jsx-runtime, lumiose/env and the required tsconfig.json.
• CLI: lumiose dev, build, preview, check, typegen, routes, lint, fmt, docs, explain, agents init and mcp; --format json and exit codes.
• MCP server: lumiose mcp for coding agents: docs, check with fixes, routes, components, compiler output, rendered HTML and dev logs.
• @lumiose/adapter-node: createServer, createHandler and createStaticHandler: serve a build with Node.
• Server build: dist/server/entry.js: export default { fetch(request, platform?) }, ctx.platform, createHandler and config; run it with Bun or Deno.
• @lumiose/query: TanStack Query for Lumiose (useQuery, useMutation, useQueryClient, QueryClientProvider), and when to use it instead of fetchJSON.

#Diagnostics

• All diagnostics: Every LUMxxxx code with its explanation and fix.

#Status of this version

Lumiose is pre-1.0, so APIs may still change between minor versions. The docs describe the designed API; where this version does not implement something yet, the page says so in a Status note. In short: