Coming from Solid

This page maps Solid 1.x, Solid Router and SolidStart to Lumiose's current API. The linked pages have the full rules.

#Mental model

The same core idea. As in Solid, a component body runs once, JSX expressions that read signals compile to bindings that update their part of the DOM, and there is no virtual DOM. Owners, onCleanup, context and untrack work the way you expect (Signals). Lumiose's names follow Solid and React where the behaviour matches, without Solid's create prefix: signal, computed, effect, store.

The differences are in the details:

• A signal is one function, not a [get, set] tuple: count() reads, count.set(1) and count.update((n) => n + 1) write.
• Props destructure safely. The compiler rewrites destructured component parameters, with defaults and ...rest, into reads of props.x, so ({ title, size = "md" }) stays reactive. No splitProps or mergeProps.
• Control flow is plain JSX. There is no <Show>, <For> or <Switch>: the compiler turns .map() into a keyed list, ternaries and && into memoised branches, and item.id === selected() inside .map() into a selector (JSX).
• Async components replace resources. A component may be async and await its data on the server and in the browser; <Suspense> and <ErrorBoundary> work as in Solid (Async components).
• Styles live with the component. .stsx files are TSX plus raw-CSS <style> blocks, scoped by where they are placed (Styles).

Server first, with islands. SolidStart renders the app on the server and hydrates all of it. In Lumiose, static and server pages ship no JavaScript, and a client:* directive at the usage site makes one component instance an island: <Todos client:load />. An spa route is the SolidStart experience: server-rendered, hydrated, client-side navigation with persistent layouts (Rendering modes).

#From Solid to Lumiose

#Reactivity

#Components and JSX

#SolidStart

#Solid Router

#What has no equivalent

#Example

A filtered todo list, in Solid:

import { createMemo, createSignal, For, Show } from "solid-js";
import { createStore } from "solid-js/store";

export function Todos(props: { title: string }) {
  const [todos, setTodos] = createStore([{ id: 1, text: "Write the docs", done: false }]);
  const [filter, setFilter] = createSignal<"all" | "open">("all");
  const visible = createMemo(() =>
    filter() === "open" ? todos.filter((todo) => !todo.done) : todos,
  );

  return (
    <section>
      <h2>{props.title}</h2>
      <button onClick={() => setFilter((f) => (f === "all" ? "open" : "all"))}>
        Show {filter() === "all" ? "open" : "all"}
      </button>
      <Show when={visible().length > 0} fallback={<p>Nothing to do.</p>}>
        <ul>
          <For each={visible()}>
            {(todo, i) => (
              <li classList={{ done: todo.done }}>
                <input
                  type="checkbox"
                  checked={todo.done}
                  onChange={() =>
                    setTodos(
                      (t) => t.id === todo.id,
                      "done",
                      (done) => !done,
                    )
                  }
                />
                {i() + 1}. {todo.text}
              </li>
            )}
          </For>
        </ul>
      </Show>
    </section>
  );
}

The same list in Lumiose, with its styles in the file. The props are destructured, the store is written directly, and the control flow is a ternary and .map():

// src/components/Todos.stsx
import { computed, signal, store } from "lumiose";

export function Todos({ title }: { title: string }) {
  const todos = store([{ id: 1, text: "Write the docs", done: false }]);
  const filter = signal<"all" | "open">("all");
  const visible = computed(() =>
    filter() === "open" ? todos.filter((todo) => !todo.done) : todos,
  );

  return (
    <section>
      <h2>{title}</h2>
      <button onClick={() => filter.update((f) => (f === "all" ? "open" : "all"))}>
        Show {filter() === "all" ? "open" : "all"}
      </button>
      {visible().length > 0 ? (
        <ul>
          {visible().map((todo, i) => (
            <li key={todo.id} class={{ done: todo.done }}>
              <input
                type="checkbox"
                checked={todo.done}
                onChange={() => {
                  todo.done = !todo.done;
                }}
              />
              {i + 1}. {todo.text}
            </li>
          ))}
        </ul>
      ) : (
        <p>Nothing to do.</p>
      )}
    </section>
  );
}

<style>
  .done { color: gray; text-decoration: line-through; }
</style>

A SolidStart route that reads with query() and createAsync() and writes with an action() becomes a page with an async component and a form action. Without JavaScript the form posts and the page re-renders with the action's data:

// src/routes/members/[id]/page.stsx
import {
  Title,
  actionData,
  fail,
  href,
  notFound,
  query,
  redirect,
  type ActionContext,
  type PageProps,
} from "lumiose";
import { Todos } from "../../../components/Todos.stsx";

export const mode = "server";

const members = new Map([["1", { name: "Ada", bio: "" }]]); // a database in a real app

export const actions = {
  async save(ctx: ActionContext<"/members/[id]">) {
    const bio = String((await ctx.formData()).get("bio") ?? "");
    if (bio.length > 200) return fail(400, { error: "Keep it under 200 characters." });
    const member = members.get(ctx.params.id) ?? notFound();
    member.bio = bio;
    redirect(href("/members/[id]", { id: ctx.params.id }));
  },
};

export default async function Member({ params }: PageProps<"/members/[id]">) {
  // One query per request and key, however many components await it.
  const member = (await query(["member", params.id], async () => members.get(params.id))) ?? notFound();
  return (
    <main>
      <Title>{member.name}</Title>
      <h1>{member.name}</h1>
      <form method="post" action="?/save">
        <textarea name="bio">{member.bio}</textarea>
        <p>{actionData<typeof actions>()?.error}</p>
        <button>Save</button>
      </form>
      <Todos client:visible title={`${member.name}'s tasks`} />
    </main>
  );
}

#Common mistakes

• Destructuring a signal tuple. const [count, setCount] = signal(0) is a type error: a signal is one function with .set() and .update().
• <Show>, <For> or <Switch>. They do not exist. Write ternaries and .map(); the compiler makes them fine-grained.
• Calling the index: i(). In .map((item, i) => …), i is used as a number; the compiler keeps it reactive. Passing it out of the callback is LUM2006.
• setStore paths. A store is written directly: todo.done = true, state.items.push(item).
• splitProps to keep props reactive. Destructure instead; the compiler keeps the reads reactive. Copying a signal's value into a variable is what freezes it (LUM2001).
• An early return on a signal. if (!user()) return <Login /> runs once, as in Solid; branch in the JSX (LUM2003).
• query(fn, "key"). Lumiose's query takes the key first, as an array: query(["user", id], fn).
• An interactive component on a page without client:*. It renders on the server, and its handlers never run. Add a directive at the usage site, or make the route spa.
• 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.
• A server function imported into an island. Importing a *.server.ts module from browser code is LUM4003. Post to a form action or call an endpoint.

#Related

• Signals and reactivity: signal, computed, effect, store, owners and scheduling.
• JSX: bindings, the compiled .map(), ternaries and selectors, class, style, attach and ref.
• Components: setup once, props destructuring, children and refs.
• Styles: <style> blocks scoped by placement.
• Async components: awaiting data, <Suspense>, <ErrorBoundary> and the request cache.
• Islands and Rendering modes: what ships to the browser.
• Routing, Data and actions and lumiose/router: the SolidStart and Solid Router side.