# 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.4.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.
- [Coming from React](/lumiose/docs/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](/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.
- [Testing](/lumiose/docs/concepts/testing): Test components with Vitest and the Lumiose Vite plugin.
- [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.

## 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` 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)
- [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)
- [LUM6001: tsconfig missing options required by Lumiose](/lumiose/docs/errors/LUM6001)