# 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
;
}
```
```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
// When the platform really wants a string:
```
Event handlers are camelCase only: `on` followed by an uppercase letter (`onClick`, `onPointerDown`). **Lowercase `on*` names are attributes in 2.0.** In 1.x `