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. The Coming from guides map another framework's concepts to the current API (they are not migration guides) and share one outline: Mental model, From framework to Lumiose (a table from its APIs to Lumiose's), What has no equivalent (and what to do instead), Example, Common mistakes and Related.

#Start here

• Getting started: Create a project, configure TypeScript and Vite, and render a first component.
• Stability: What 0.x allows, the 1.0 criteria and the API freeze, supported Node.js versions and browsers, and who maintains Lumiose.
• When not to use Lumiose: The cases where another framework is the better choice today, and what to use instead.

#Coming from

• React: Hooks mapped to signals, React 19's forms and server components mapped to form actions and islands, what goes away (the rules of hooks, dependency arrays, stale closures, memoization) and the mistakes React habits cause.
• Next.js: The App Router mapped to Lumiose: the same route file names, server components by default, client:* islands instead of "use client", form actions instead of server actions, metadata, caching and rendering modes.
• React Router: Framework mode mapped to Lumiose: file routes instead of routes.ts, async components instead of loaders, form actions and submit() instead of actions and fetchers, middleware, the document and custom servers.
• Solid: The closest model, so mostly differences: signal and store APIs, props destructuring, control flow as plain JSX, async components instead of resources, .stsx styles, islands, and SolidStart and Solid Router mapped to file routes, endpoints and form actions.
• Astro: The same page model with one component model instead of two: .astro files and framework islands mapped to .stsx components, typed ?client scripts, file routes, endpoints, form actions and Markdown imports, and where Astro is still ahead.

#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.
• Dev tools: The in-page inspector of lumiose dev (Alt+Shift+L): the component tree with props and source locations, signals with their dependents and last write, islands with their hydration state, why something updated, and Alt+click to open any element's source.
• Testing: Component tests with Vitest and Testing Library (queries and user-event), server rendering as strings, and end-to-end tests with Playwright.
• 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.
• Payments with Stripe Checkout: Checkout started from a form action, a return page, and webhooks received by a route.ts endpoint that verifies Stripe's signature.
• Content from Sanity: Sanity content read in async components and prerendered, draft previews on a server-rendered route behind a secret, and static rebuilds from Sanity's webhook.
• Tracing with OpenTelemetry: Spans for requests, their phases and client navigations from the instrumentation files, a relay for the browser's spans, and setups for OpenObserve, SigNoz and Datadog.
• Error reporting with Sentry: Server errors from onRequestError and browser errors from onError reported to Sentry, with the source maps of both builds uploaded by Sentry's Vite plugin.
• Product analytics with PostHog: PostHog started in src/instrumentation.client.ts, page views on MPA pages and SPA navigations (afterNavigate), events from islands and feature flags evaluated on the server.
• Editors: The language server in Neovim and Helix (file type, root markers, the server command), what works in Zed today, and GitHub highlighting through .gitattributes.
• Web components: Custom elements and web-component libraries: defining them in the browser, typing them in JSX, properties versus attributes (React 19's rule), events with on:, server rendering, and the Custom Elements Everywhere score (100).

#STSX

• STSX: .stsx files outside Lumiose. @lumiose/stsx is a Vite plugin that compiles their scoped <style> blocks for React, React Router and Solid, with the same placement rules, $name constants and scopedStyles option. Its docs ship in its package: node_modules/@lumiose/stsx/docs/llms.txt indexes them.

#UI

• UI components: @lumiose/ui, accessible and unstyled primitives on native elements, server-rendered without hydration, with the optional default theme. Its docs ship in its own package and match its own version: node_modules/@lumiose/ui/docs/llms.txt indexes them, and in a project that depends on it lumiose docs ui and lumiose docs dialog print them and the MCP server's ui_components tool lists the components.

#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, beforeNavigate/afterNavigate 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 change in any minor version (Stability). The docs describe the designed API; where this version does not implement something yet, the page says so in a Status note. In short: