# Solid 2.0 — quick migration guide This is a short, practical guide for migrating from Solid 1.x to Solid 2.0’s APIs. It focuses on the changes you’ll hit most often and shows “before/after” examples. ## Quick checklist (start here) - **Imports**: some 1.x subpath imports moved to `@solidjs/*` packages (and store helpers moved into `solid-js`). - **JSX types**: web projects should set `jsxImportSource` to `@solidjs/web`; `solid-js` no longer owns JSX runtime types. - **Batching/reads**: setters don’t immediately change what reads return; values become visible after the microtask batch flushes (or via `flush()`). - **Effects**: `createEffect` is split (compute → apply). Cleanup is usually “return a cleanup function”. - **Lifecycle**: `onMount` is replaced by `onSettled` (and it can return cleanup). - **Async UI**: use `` for first readiness; use `isPending(() => expr)` for “a change is on the way” indicators (input-driven refetches and `affects()` declarations — a bare `refresh()` is silent). - **Lists**: `Index` is gone; use ``. Default `For` receives raw items, while `keyed={false}` receives item accessors and a stable numeric index. - **Stores**: setters are draft-first; 1.x path-argument setters become draft writes to the same path. - **Plain values**: `snapshot(store)` replaces `unwrap(store)` when you need a plain non-reactive value. - **DOM**: `/*@once*/` and `use:` directives are removed from the public JSX model; use normal reactive JSX, `untrack` for intentional one-time JavaScript reads, and `ref` directive factories (including array refs). Previously tolerated `class:` / `style:` namespace syntax is no longer special; use `class` / `style` object values. - **Refs**: ref callbacks are now unowned — `getOwner()` is `null` inside them, so 1.x-style `onCleanup()` registration inside a ref callback no longer works. Keep lifecycle work in an owned scope: `onSettled` in the component body, or the setup half of a directive factory. - **Helpers**: `mergeProps` → `merge`, `splitProps` → `omit`. ## Core behavior changes ### Imports: where things live now In Solid 2.0, the DOM/web runtime is its own package, and some “subpath imports” from 1.x are gone. ```ts // 1.x (DOM runtime) import { render, hydrate } from "solid-js/web"; // 2.0 import { render, hydrate } from "@solidjs/web"; ``` ```ts // 1.x (stores) import { createStore } from "solid-js/store"; // 2.0 (stores are exported from solid-js) import { createStore, reconcile, snapshot } from "solid-js"; ``` ```ts // 1.x (hyperscript / alternate JSX factory) import h from "solid-js/h"; // 2.0 import h from "@solidjs/h"; ``` ```ts // 1.x (tagged-template HTML) import html from "solid-js/html"; // 2.0 import html from "@solidjs/html"; ``` ```ts // 1.x (custom renderers) import { createRenderer } from "solid-js/universal"; // 2.0 import { createRenderer } from "@solidjs/universal"; ``` ### TypeScript JSX: `solid-js` → renderer package In 2.0, `solid-js` does not export a JSX namespace or `jsx-runtime` type entries. The core package owns renderer-neutral component types; renderer packages own JSX types. For web apps, update `tsconfig.json`: ```json { "compilerOptions": { "jsx": "preserve", "jsxImportSource": "@solidjs/web" } } ``` If you previously used `"jsxImportSource": "solid-js"` or imported `solid-js/jsx-runtime`, switch to `@solidjs/web`: ```ts // 1.x / earlier 2.0 betas import type { JSX, ComponentProps } from "solid-js"; // 2.0 import type { JSX, ComponentProps } from "@solidjs/web"; ``` For renderer-neutral component APIs, use `Element` from `solid-js` instead of `JSX.Element`: ```ts import type { Component, Element } from "solid-js"; type Wrapper = Component<{ children?: Element }>; ``` For hyperscript JSX, set `jsxImportSource` to `@solidjs/h`. Custom renderers should provide their own `jsx-runtime` and `jsx-dev-runtime` type entries. See [RFC 09 — TypeScript and JSX ownership](09-typescript-jsx.md) for the full design. ### Batching & reads: values update after flush In Solid 2.0, updates are batched by default (microtasks). A key behavioral change is that **setters don’t immediately update what reads return** — the new value becomes visible when the batch is flushed (next microtask), or immediately if you call `flush()`. ```js const [count, setCount] = createSignal(0); setCount(1); count(); // still 0 flush(); count(); // now 1 ``` Use `flush()` sparingly (it forces the system to “catch up now”). It’s most useful in tests, or in rare imperative code where you truly need a synchronous “settled now” point. ### Effects, lifecycle, and cleanup Solid 2.0 splits effects into two phases: - a **compute** function that runs in the reactive tracking phase and returns a value - an **apply** function that receives that value and performs side effects (and can return cleanup) ```js // 1.x (single function effect) createEffect(() => { el().title = name(); }); // 2.0 (split effect: compute -> apply) createEffect( () => name(), value => { el().title = value; } ); ``` The `initialValue` parameter from 1.x is gone. In 2.0, the compute function receives `prev` (which is `undefined` on the first run). If you need a default, use a default parameter: ```js // 1.x (initialValue as second arg) createEffect(prev => { console.log("changed from", prev, "to", count()); return count(); }, 0); // 2.0 (default parameter for prev, apply function is second arg) createEffect( (prev = 0) => count(), (value, prev) => { console.log("changed from", prev, "to", value); } ); ``` This same change applies to `createMemo` — the second argument is now `options`, not an initial value: ```js // 1.x const doubled = createMemo(prev => count() * 2, 0); // 2.0 (no initialValue arg; prev is undefined on first run) const doubled = createMemo(() => count() * 2); ``` Cleanup usually lives on the apply side now: ```js // 1.x createEffect(() => { const id = setInterval(() => console.log(name()), 1000); onCleanup(() => clearInterval(id)); }); // 2.0 createEffect( () => name(), value => { const id = setInterval(() => console.log(value), 1000); return () => clearInterval(id); } ); ``` If you used `onMount`, the closest replacement is `onSettled` (and it can also return cleanup): ```js // 1.x onMount(() => { measureLayout(); }); // 2.0 onSettled(() => { measureLayout(); const onResize = () => measureLayout(); window.addEventListener("resize", onResize); return () => window.removeEventListener("resize", onResize); }); ``` #### Nested `createRoot` is owned by its parent In 1.x a `createRoot` created inside another owner was kept out of that owner's `owned` list, so it lived until its own `dispose()` was called. In 2.0 a root created inside an existing owner is a child of that owner and is disposed with it (its own `dispose()` still works for tearing it down earlier). To keep the 1.x “lives until I dispose it” behavior, detach explicitly with `runWithOwner(null, ...)`: ```js // 1.x (nested root survives the parent) const dispose = createRoot(dispose => { onCleanup(() => controller.destroy()); return dispose; }); // 2.0 (same lifetime: detach explicitly) const dispose = runWithOwner(null, () => createRoot(dispose => { onCleanup(() => controller.destroy()); return dispose; }) ); ``` See [RFC 02 — Ownership: `createRoot` is owned by the parent by default](02-signals-derived-ownership.md#ownership-createroot-is-owned-by-the-parent-by-default). ### Dev warnings you’ll likely see (and how to fix them) These are **dev-only diagnostics** meant to catch bugs earlier. Some are warnings (console); others are errors (throw). See [RFC 08](08-dev-diagnostics.md) for the full reference. #### “Top-level reactive read” in a component In 2.0, reading reactive values at the top level of a component body (including destructuring props) will warn. The fix is to move the read to where the value is used: JSX, a memo, an effect's compute function, the event handler, or an accessor passed to a hook. If the value must never update and is never downstream of async, `untrack` makes the one-time read explicit; do not use it just to silence the warning. ```jsx // ❌ 2.0 warns (top-level reactive read) function Bad(props) { const n = props.count; return
{n}
; } // ✅ read inside JSX/expression function Ok(props) { return
{props.count}
; } ``` ```jsx // ❌ 2.0 warns (common: destructuring in args) function BadArgs({ title }) { return

{title}

; } // ✅ keep props object, or destructure inside a memo/effect function OkArgs(props) { return

{props.title}

; } ``` #### “Write inside reactive scope” (owned scope) Writing to signals/stores inside a reactive scope **throws** in dev. Usually you want: - derive values with `createMemo` (no write-back) - write in event handlers / actions - return cleanup from effect apply functions (instead of writing during tracking) ```js // ❌ throws: writing from inside a memo createMemo(() => setDoubled(count() * 2)); // ✅ derive instead of writing back const doubled = createMemo(() => count() * 2); ``` If you truly have an **internal** signal that needs to be written from within owned scope (not app state), opt in narrowly with `ownedWrite: true`. ### `/*@once*/` JSX marker The `/*@once*/` JSX compiler marker is no longer part of Solid's public JSX model. Do not treat it as a JSX form of `untrack`, and do not look for a marker-based replacement. Most uses should become normal reactive JSX. If a value should update, leave the read in JSX or another reactive scope: ```jsx // 1.x // 2.0: keep reactive values reactive ``` For DOM initial/default state, use the platform default prop instead of freezing a reactive value: ```jsx // 1.x // 2.0 ``` If you truly need the old “read this once” behavior, the replacement is `untrack` in JavaScript, outside JSX: ```jsx const value = untrack(() => props.value); ``` Keep this code narrow. It is not the common path and should not be used to opt reactive values out of updates, or to silence `STRICT_READ_UNTRACKED`. Seed local state with a writable derived signal (`createSignal(() => props.initial)`) instead. ## Async data & transitions ### `Suspense` / `ErrorBoundary` → `Loading` / `Errored` ```jsx // 1.x }> // 2.0 }> ``` ### `createResource` → async computations + `Loading` The basic pattern: replace `createResource` with an async `createMemo` (or `createStore(fn)` for collections), and wrap consumers in `Loading`: ```js // 1.x const [user] = createResource(id, fetchUser); // 2.0 const user = createMemo(() => fetchUser(id())); ``` ```jsx }> ``` The resource tuple features map to standalone APIs: | 1.x resource feature | 2.0 replacement | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resource.loading` | `Loading` (initial), `isPending(() => resource())` (in-flight input change); a bare `refresh()` is silent — use `affects(resource); refresh(resource)` or a co-written optimistic flag for refetch affordances | | `resource.error` | `Errored` boundary or effect `error` option | | `refetch()` | `refresh(resource)` | | `mutate()` | `createOptimisticStore` + `action` (see [RFC 06](06-actions-optimistic.md)) | See [RFC 05 — createResource migration](05-async-data.md#createresource--async-computations--loading) for detailed before/after examples of each pattern. ### Initial loading vs in-flight changes: `Loading` vs `isPending` - **`Loading`**: initial “not ready yet” UI boundary. - **`isPending(fn)`**: active pending read for the exact expression in `fn` — `true` while a value change is in flight for it (an input changed, or in-flight work declared it with `affects`); a bare `refresh()`/poll of the same inputs is silent. When the expression can be not ready, place it under the `Loading` boundary that should own initial fallback UI. It can live outside the boundary when it only reads upstream state that cannot be not ready. ```jsx const listPending = () => isPending(() => users() || posts()); }> {/* subtle "updating…" indicator while a new query loads */} ; ``` ### Peeking in-flight values: `latest(fn)` ```js const latestId = () => latest(id); ``` ### “Refetch/refresh” patterns → `refresh()` ```js // After a server write, explicitly recompute a derived read: refresh(storeOrProjection); ``` ### Mutations: `action(...)` + optimistic helpers In 1.x, mutations often ended up as “call an async function, flip some flags, then manually refetch”. In 2.0, the recommended shape is: - wrap mutations in `action(...)` - use `createOptimistic` / `createOptimisticStore` for optimistic UI - call `refresh(...)` at the end to reconcile derived reads with the source of truth ```js const [todos] = createStore(() => api.getTodos(), { list: [] }); const [optimisticTodos, setOptimisticTodos] = createOptimisticStore({ list: [] }); const addTodo = action(function* (todo) { // optimistic UI setOptimisticTodos(s => s.list.push(todo)); // server write yield api.addTodo(todo); // recompute reads derived from the source-of-truth refresh(todos); }); ``` ## Stores ### Draft-first setters ```js // 2.0 preferred: produce-style draft updates setStore(s => { s.user.address.city = "Paris"; }); // 1.x path setters become draft writes to the same path: // setStore("user", "address", "city", "Paris") → the update above ``` ### `unwrap(store)` → `snapshot(store)` ```js const plain = snapshot(store); JSON.stringify(plain); ``` ### `mergeProps` / `splitProps` → `merge` / `omit` ```js // 1.x const merged = mergeProps(defaults, overrides); // 2.0 const merged = merge(defaults, overrides); ``` One behavioral gotcha: **`undefined` is treated as a real value** (it overrides), not “skip this key”. ```js const merged = merge({ a: 1, b: 2 }, { b: undefined }); // merged.b is undefined ``` ```js // 1.x const [local, rest] = splitProps(props, ["class", "style"]); // 2.0 const rest = omit(props, "class", "style"); ``` ### New function forms: `createSignal(fn)` and `createStore(fn)` `createSignal(fn)` creates a **writable derived signal** (think “writable memo”): ```js const [count, setCount] = createSignal(0); const [doubled] = createSignal(() => count() * 2); ``` `createStore(fn, seed)` creates a **derived store** using the familiar `createStore` API: ```js const [items] = createStore(() => api.listItems(), []); const [cache] = createStore( draft => { draft.total = items.length; }, { total: 0 } ); ``` ## Control flow ### List rendering: `Index` is gone, and `For` handles each keying mode If you used `Index`, it’s now `For` with `keyed={false}`. The callback shape depends on the keying mode: - Default `For` / `keyed={true}` receives the raw item and an index accessor: `(item, i)`. - `keyed={false}` receives an item accessor and a stable numeric index: `(item, i)`. This is the direct `Index` replacement. - `keyed={(item) => key}` receives item and index accessors. ```jsx // 1.x {(item, i) => } // 2.0 {(item, i) => } ``` Prefer literal `keyed` modes for function children. A dynamic boolean `keyed={condition()}` makes the callback shape ambiguous. ### Function children may receive accessors Some control-flow APIs pass accessors into function children so the value is always safe to read. This is most relevant when migrating `Index` to `For keyed={false}`: ```jsx }> {u => } {() => } ``` ### Dynamic components: `createDynamic` / `` → `dynamic` factory `createDynamic(source, props): JSX.Element` is replaced by a `lazy`-style factory, `dynamic(source): Component

`. The factory returns a stable component whose identity is driven by a reactive (and optionally async) source — children, refs, and reactive props flow through the normal JSX path, so the returned value is usable anywhere a component is. ```jsx // 1.x style import { Dynamic } from "solid-js/web"; ; // 2.0 — hoist a factory; use it like any component import { dynamic } from "@solidjs/web"; const Active = dynamic(() => (isEditing() ? Editor : Viewer)); return ; ``` Async sources compose with `Loading`/Suspense through the normal `NotReadyError` flow — no wrapper primitive or `await` in user code. `` still exists in 2.0 but is **deprecated** (no runtime warning); existing code keeps working, new code should use the factory. It is the same primitive with a worse shape: the tag travels in the props bag, so every instance pays a `merge` at the call site, an `omit` inside, and a fresh factory memo that a JSX wrapper has nowhere to hoist. Replace it with a `dynamic()` factory hoisted to the component body (or the module, for a constant tag); inside a `` callback the callback body is the place. Direct callers of the old `createDynamic(source, props)` compose manually as `createComponent(dynamic(source), props)`. ### Coordinating loading boundaries: `SuspenseList` → `Reveal` `SuspenseList` is replaced by `Reveal`, which coordinates sibling `Loading` boundaries. Ordering is controlled by a single `order` prop with three values: `"sequential"` (default, matches `revealOrder="forwards"`), `"together"` (matches `revealOrder="together"`), and `"natural"` (new in 2.0 — no in-group ordering). A separate `collapsed` boolean covers the former `tail="collapsed"` case; it is only consulted when `order="sequential"` and is ignored otherwise. ```jsx // 1.x }> }> // 2.0 — default sequential ordering }> }> // 2.0 — reveal the whole group at once }> }> // 2.0 — nested natural group that reveals independently within its slot }>

{/* Held on their fallbacks until the outer frontier reaches this slot. Once released, each card reveals as its own data resolves. */} }> }> ``` > Note: in earlier 2.0 betas `Reveal` exposed a boolean `together` prop. That prop has been replaced by `order="together"`. `collapsed` still exists; it is a sequential-only knob and has no effect under `order="together"` or `order="natural"`. Nesting semantics, the outer/inner ordering matrix, and SSR caveats are documented in [Control flow → Reveal](./03-control-flow.md#reveal-timing-reveal). ## DOM ### Attributes & events: closer to HTML (and fewer namespaces) Solid 2.0 aims to be more “what you write is what the platform sees”: - built-in attributes are treated as **attributes** (not magically mapped properties), and are generally **lowercase** - boolean attributes are presence/absence (`muted={true}` adds it, `muted={false}` removes it) - `attr:`, `bool:`, and `on:` namespaces are removed (you typically don’t need them) The compiler rejects the removed forms. Written on a native element, `on:`, `oncapture:`, `attr:`, `bool:`, `use:` and `classList` are compile errors, and the message names the 2.0 replacement. On components they are still ordinary prop names. `prop:` and the XML namespaces (`xlink:`, `xml:`, `xmlns:`) compile as before. ```jsx