# Lumiose

> Lumiose is a web framework for everything from static sites and SPAs to full-stack apps: TSX with scoped CSS built in, signals, and 0 kB of JavaScript until a page needs it.

These docs match lumiose 0.7.0. Installed projects have them in `node_modules/lumiose/docs`;
`lumiose docs <topic>` prints one and `lumiose explain <code>` explains a diagnostic.

## Start here

- [Getting started](/lumiose/docs/getting-started): Create a project, configure TypeScript and Vite, and render a first component.
- [Stability](/lumiose/docs/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](/lumiose/docs/when-not-to-use): The cases where another framework is the better choice today, and what to use instead.

## Coming from

- [React](/lumiose/docs/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](/lumiose/docs/coming-from/nextjs): 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](/lumiose/docs/coming-from/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](/lumiose/docs/coming-from/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](/lumiose/docs/coming-from/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](/lumiose/docs/concepts/components): Setup-once function components, props, children, refs and the `.stsx`/`.tsx`/`.ts` file types.
- [Signals and reactivity](/lumiose/docs/concepts/signals): `signal`, `computed`, `effect`, `store`, owners, context and scheduling.
- [Sharing state](/lumiose/docs/concepts/state): Component, context and module-scope state; recipes for stores with actions, families, persisted signals, external stores and state shared by islands.
- [JSX](/lumiose/docs/concepts/jsx): Bindings, compiled idioms (`.map`, ternaries), `class`, `style`, events, `bind:`, `attach` and `ref`.
- [Styles](/lumiose/docs/concepts/styles): Raw-CSS `<style>` blocks scoped by placement, `<style global>`, JS values in styles (`$name`), build-time math and runtime values.
- [Async components](/lumiose/docs/concepts/async): `async` components on server and client, `<Suspense>`, `<ErrorBoundary>`, re-runs and in-flight state.
- [Islands](/lumiose/docs/concepts/islands): `client:*` directives, serializable props, slots and server-only boundaries.
- [Routing](/lumiose/docs/concepts/routing): File routes, layouts, params, typed `href()`, error pages and the SPA router.
- [Internationalization](/lumiose/docs/concepts/i18n): Locale prefixes, per-page locale declarations, `locale()`, locale-aware `href()`, `hreflang` and canonical links, detection on entry.
- [Data and actions](/lumiose/docs/concepts/data-and-actions): Read data with async components, serve endpoints, mutate with form actions and `submit()`.
- [Server](/lumiose/docs/concepts/server): Request context, middleware, cookies, env, redirects and error helpers.
- [Rendering modes](/lumiose/docs/concepts/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](/lumiose/docs/concepts/svg): `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](/lumiose/docs/concepts/content): `.md` and `.html` files as static components; GFM, heading ids, frontmatter and its hook, scoped `<style>`, client `<script>`.
- [Head and document](/lumiose/docs/concepts/head): `<Title>`, `<Meta>`, `<Head>` and a custom `document.stsx`.
- [Compiler and diagnostics](/lumiose/docs/concepts/compiler): What the compiler does with `.stsx`/`.tsx`, and how `LUMxxxx` diagnostics work.
- [Dev tools](/lumiose/docs/concepts/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](/lumiose/docs/concepts/testing): Component tests with Vitest and Testing Library (queries and user-event), server rendering as strings, and end-to-end tests with Playwright.
- [Security](/lumiose/docs/concepts/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](/lumiose/docs/guides/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](/lumiose/docs/guides/icons): 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](/lumiose/docs/guides/i18n): 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](/lumiose/docs/guides/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](/lumiose/docs/guides/stripe): 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](/lumiose/docs/guides/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](/lumiose/docs/guides/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](/lumiose/docs/guides/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](/lumiose/docs/guides/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](/lumiose/docs/guides/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](/lumiose/docs/guides/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).

## UI

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

## Reference

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

## Diagnostics

- [LUM1001: Syntax error](/lumiose/docs/errors/LUM1001)
- [LUM1002: Unsupported by this compiler version](/lumiose/docs/errors/LUM1002)
- [LUM1003: Scanner ambiguity](/lumiose/docs/errors/LUM1003)
- [LUM1004: Unclosed `<style>` block](/lumiose/docs/errors/LUM1004)
- [LUM1005: Unknown `<style>` attribute](/lumiose/docs/errors/LUM1005)
- [LUM1006: Raw CSS in a `.tsx` file](/lumiose/docs/errors/LUM1006)
- [LUM1007: `await using` in a component](/lumiose/docs/errors/LUM1007)
- [LUM1008: `<script>` in a Markdown file](/lumiose/docs/errors/LUM1008)
- [LUM1009: Content nested too deeply](/lumiose/docs/errors/LUM1009)
- [LUM1010: Source nested too deeply](/lumiose/docs/errors/LUM1010)
- [LUM2001: Stale derived value](/lumiose/docs/errors/LUM2001)
- [LUM2002: Signal write during render](/lumiose/docs/errors/LUM2002)
- [LUM2003: Reactive early return](/lumiose/docs/errors/LUM2003)
- [LUM2004: Component called as a function](/lumiose/docs/errors/LUM2004)
- [LUM2005: Children inserted twice](/lumiose/docs/errors/LUM2005)
- [LUM2006: Reactive index escapes its callback](/lumiose/docs/errors/LUM2006)
- [LUM2007: Own signal read in an async body](/lumiose/docs/errors/LUM2007)
- [LUM2008: Unsupported list key](/lumiose/docs/errors/LUM2008)
- [LUM3005: Unused scoped selector](/lumiose/docs/errors/LUM3005)
- [LUM3008: Non-constant `$` reference](/lumiose/docs/errors/LUM3008)
- [LUM3009: Hyphenated `$` reference](/lumiose/docs/errors/LUM3009)
- [LUM3010: Misplaced `<style>` block](/lumiose/docs/errors/LUM3010)
- [LUM3011: `<style>` as the root or in an expression](/lumiose/docs/errors/LUM3011)
- [LUM3012: Custom property set but never read](/lumiose/docs/errors/LUM3012)
- [LUM3013: `$` reference before its declaration](/lumiose/docs/errors/LUM3013)
- [LUM3014: CSS syntax error](/lumiose/docs/errors/LUM3014)
- [LUM3015: Invalid CSS ignored](/lumiose/docs/errors/LUM3015)
- [LUM3016: Invalid `:global()` or `:deep()` selector](/lumiose/docs/errors/LUM3016)
- [LUM3017: Invalid CSS value](/lumiose/docs/errors/LUM3017)
- [LUM3018: Unitless number from a `$` reference](/lumiose/docs/errors/LUM3018)
- [LUM3019: Unit separated from a `$` reference](/lumiose/docs/errors/LUM3019)
- [LUM3020: Unknown CSS property](/lumiose/docs/errors/LUM3020)
- [LUM3021: Unsafe `$` constant value](/lumiose/docs/errors/LUM3021)
- [LUM4001: Island component is not exported](/lumiose/docs/errors/LUM4001)
- [LUM4002: Non-serializable island prop](/lumiose/docs/errors/LUM4002)
- [LUM4003: Server-only module in a client graph](/lumiose/docs/errors/LUM4003)
- [LUM4004: Browser API at module scope](/lumiose/docs/errors/LUM4004)
- [LUM4006: Hydration mismatch](/lumiose/docs/errors/LUM4006)
- [LUM4007: Non-serializable awaited value](/lumiose/docs/errors/LUM4007)
- [LUM4008: Module-scope signal written during SSR](/lumiose/docs/errors/LUM4008)
- [LUM4009: Unsafe URL blocked in a URL attribute](/lumiose/docs/errors/LUM4009)
- [LUM4010: Island reads context provided by the page](/lumiose/docs/errors/LUM4010)
- [LUM4011: Non-serializable scoped state value](/lumiose/docs/errors/LUM4011)
- [LUM5001: Request API used during prerender](/lumiose/docs/errors/LUM5001)
- [LUM5002: Invalid route file](/lumiose/docs/errors/LUM5002)
- [LUM5003: Duplicate route](/lumiose/docs/errors/LUM5003)
- [LUM5004: Head or status change inside a streamed boundary](/lumiose/docs/errors/LUM5004)
- [LUM5005: Non-GET method in a static endpoint](/lumiose/docs/errors/LUM5005)
- [LUM5006: Prerendered page that renders only in the browser](/lumiose/docs/errors/LUM5006)
- [LUM5007: Route param named `locale`](/lumiose/docs/errors/LUM5007)
- [LUM5008: Folder middleware covering prerendered routes](/lumiose/docs/errors/LUM5008)
- [LUM5009: Boundary still pending when streamTimeout expired](/lumiose/docs/errors/LUM5009)
- [LUM6001: tsconfig missing options required by Lumiose](/lumiose/docs/errors/LUM6001)