Solid 2.0.0 landed on npm on 17 November 2026. It is the biggest change to SolidJS since 1.0: a new signals engine, a new package layout, built-in async and transitions, and a cleaner effect model. Your 1.x code will not run unchanged, but most changes follow clear patterns. This tutorial covers the changes you’ll hit first, with before/after code, so you can plan an upgrade or start a fresh project the 2.0 way.
Everything here is based on the official Solid 2.0 migration guide and the solid-js 2.0.0 changelog in the solidjs/solid repository.
Install
npm install solid-js@2 @solidjs/web@2
Then point TypeScript’s JSX types at the web renderer. In 2.0, solid-js no longer owns the JSX namespace:
{
"compilerOptions": {
"jsx": "preserve",
"jsxImportSource": "@solidjs/web"
}
}
Make sure the Solid plugin for your bundler supports 2.0 before upgrading an existing app.
1. New import paths
The DOM runtime is now its own package, and stores moved into the core:
// 1.x
import { render } from "solid-js/web";
import { createStore } from "solid-js/store";
// 2.0
import { render } from "@solidjs/web";
import { createStore, reconcile, snapshot } from "solid-js";
Likewise, solid-js/h → @solidjs/h, solid-js/html → @solidjs/html and solid-js/universal → @solidjs/universal. Types such as JSX and ComponentProps now come from @solidjs/web.
2. Batching: setters don’t update reads immediately
This is the behaviour change most likely to surprise you. Updates are batched by microtask by default, so a read straight after a write still returns the old value until the batch flushes:
import { createSignal, flush } from "solid-js";
const [count, setCount] = createSignal(0);
setCount(1);
console.log(count()); // 0 — not flushed yet
flush();
console.log(count()); // 1
batch is gone because batching is the default. Use flush() sparingly, mainly in tests or in rare imperative code that needs a “settled now” point.
3. Effects are split into compute and apply
createEffect now takes two functions. The first one tracks dependencies and returns a value. The second one receives that value, performs the side effect, and can return a cleanup function:
// 1.x
createEffect(() => {
document.title = `${unread()} unread`;
});
// 2.0
createEffect(
() => unread(),
value => {
document.title = `${value} unread`;
}
);
Cleanup moves to the apply side:
createEffect(
() => pollEvery(),
ms => {
const id = setInterval(refreshInbox, ms);
return () => clearInterval(id);
}
);
The old initialValue argument is gone from both createEffect and createMemo. The second argument of createMemo is now an options object, and prev is undefined on the first run, so use a default parameter if you need one. The on helper is no longer needed.
onMount becomes onSettled, which can also return cleanup:
import { onSettled } from "solid-js";
onSettled(() => {
const onResize = () => measureLayout();
window.addEventListener("resize", onResize);
return () => window.removeEventListener("resize", onResize);
});
4. Async data without createResource
createResource is removed. An async createMemo plus a <Loading> boundary replaces it, and Suspense is renamed Loading:
import { createSignal, createMemo, Loading, Errored } from "solid-js";
const [userId, setUserId] = createSignal(1);
const user = createMemo(() =>
fetch(`/api/users/${userId()}`).then(r => r.json())
);
function Profile() {
return (
<Errored fallback={<p>Could not load the user.</p>}>
<Loading fallback={<p>Loading…</p>}>
<h2>{user().name}</h2>
</Loading>
</Errored>
);
}
ErrorBoundary is renamed Errored. For “updating…” indicators after the first load, use isPending:
import { isPending, Show } from "solid-js";
<Show when={isPending(() => user())}>
<small>Refreshing…</small>
</Show>
To re-ask for data after a server write, call refresh(user). It is quiet by design, so a bare refresh() doesn’t flip isPending.
5. Mutations with action and optimistic UI
2.0 has a standard shape for writes: wrap them in action(...), show optimistic state with createOptimisticStore, and refresh the source of truth at the end:
import { createStore, createOptimisticStore, action, refresh } from "solid-js";
const [todos] = createStore(() => api.getTodos(), { list: [] });
const [optimisticTodos, setOptimisticTodos] = createOptimisticStore({ list: [] });
const addTodo = action(function* (todo) {
setOptimisticTodos(s => s.list.push(todo)); // instant UI
yield api.addTodo(todo); // server write
refresh(todos); // reconcile with the server
});
Optimistic writes revert automatically when the transition completes, so the UI can’t drift away from the server state.
6. Stores: draft-first setters
Store setters now work like produce did in 1.x: you mutate a draft. Path-style setters become plain draft writes:
const [store, setStore] = createStore({ user: { address: { city: "Delhi" } } });
// 1.x: setStore("user", "address", "city", "Paris")
setStore(s => {
s.user.address.city = "Paris";
});
unwrap is renamed snapshot, which gives you a plain, non-reactive copy, for example before calling JSON.stringify. createMutable is removed, so use createStore with draft setters instead.
7. Lists, props helpers and context
Lists. Index is gone. Use <For keyed={false}>, which passes an item accessor and a stable index:
// 1.x
<Index each={rows()}>{(row, i) => <Row row={row()} index={i} />}</Index>
// 2.0
<For each={rows()} keyed={false}>
{(row, i) => <Row row={row()} index={i} />}
</For>
Props helpers. mergeProps → merge and splitProps → omit. Note that undefined now overrides a value instead of being skipped:
const rest = omit(props, "class", "style");
const merged = merge({ a: 1, b: 2 }, { b: undefined }); // merged.b === undefined
Context. The context object is the provider, and a default-less context returns T (it throws if no provider is mounted), so wrapper hooks that only existed to narrow types can go:
const Theme = createContext("light");
<Theme value="dark">{props.children}</Theme>;
8. DOM changes
classList→classwith object/array forms:<div class={["card", { active: isActive() }]} />.use:directives are removed. Userefdirective factories instead./*@once*/is gone. Keep values reactive, usedefaultValuefor initial input state, oruntrack()in JavaScript for an intentional one-time read.- Ref callbacks are no longer owned, so
onCleanup()inside them won’t work. Do lifecycle work inonSettledinstead.
9. New dev warnings you’ll see
Two diagnostics catch real bugs:
- Top-level reactive reads in a component body, including destructured props, now warn. Read props inside JSX (
props.title) instead ofconst { title } = props. - Writes inside a reactive scope throw in development. Derive with
createMemorather than calling a setter inside a memo.
// ❌ warns in 2.0
function Title({ text }) { return <h1>{text}</h1>; }
// ✅
function Title(props) { return <h1>{props.text}</h1>; }
Upgrade plan
- Read the official migration guide end to end.
- Update imports (
solid-js/web→@solidjs/web,solid-js/store→solid-js) andjsxImportSource. - Rename
Suspense/ErrorBoundary/mergeProps/splitProps/onMount/unwrap. - Convert effects to the compute/apply form and move cleanups to return values.
- Replace
createResourcewith async memos and<Loading>. - Run the app in dev mode and fix every top-level-read and owned-write diagnostic.
- Add
flush()to tests that read immediately after a write.
Takeaway
Solid 2.0 asks for real migration work, but the result is a more predictable model: batched updates, explicit compute/apply effects, and first-class async with Loading, isPending, action and optimistic stores. Start with the import and rename changes, then let the new dev diagnostics guide you through the rest.
