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.
- Imports: some 1.x subpath imports moved to
@solidjs/*packages (and store helpers moved intosolid-js). - JSX types: web projects should set
jsxImportSourceto@solidjs/web;solid-jsno 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:
createEffectis split (compute → apply). Cleanup is usually “return a cleanup function”. - Lifecycle:
onMountis replaced byonSettled(and it can return cleanup). - Async UI: use
<Loading>for first readiness; useisPending(() => expr)for “a change is on the way” indicators (input-driven refetches andaffects()declarations — a barerefresh()is silent). - Lists:
Indexis gone; use<For keyed={false}>. DefaultForreceives raw items, whilekeyed={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)replacesunwrap(store)when you need a plain non-reactive value. - DOM:
/*@once*/anduse:directives are removed from the public JSX model; use normal reactive JSX,untrackfor intentional one-time JavaScript reads, andrefdirective factories (including array refs). Previously toleratedclass:/style:namespace syntax is no longer special; useclass/styleobject values. - Refs: ref callbacks are now unowned —
getOwner()isnullinside them, so 1.x-styleonCleanup()registration inside a ref callback no longer works. Keep lifecycle work in an owned scope:onSettledin the component body, or the setup half of a directive factory. - Helpers:
mergeProps→merge,splitProps→omit.
In Solid 2.0, the DOM/web runtime is its own package, and some “subpath imports” from 1.x are gone.
// 1.x (DOM runtime)
import { render, hydrate } from "solid-js/web";
// 2.0
import { render, hydrate } from "@solidjs/web";// 1.x (stores)
import { createStore } from "solid-js/store";
// 2.0 (stores are exported from solid-js)
import { createStore, reconcile, snapshot } from "solid-js";// 1.x (hyperscript / alternate JSX factory)
import h from "solid-js/h";
// 2.0
import h from "@solidjs/h";// 1.x (tagged-template HTML)
import html from "solid-js/html";
// 2.0
import html from "@solidjs/html";// 1.x (custom renderers)
import { createRenderer } from "solid-js/universal";
// 2.0
import { createRenderer } from "@solidjs/universal";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:
{
"compilerOptions": {
"jsx": "preserve",
"jsxImportSource": "@solidjs/web"
}
}If you previously used "jsxImportSource": "solid-js" or imported solid-js/jsx-runtime, switch to @solidjs/web:
// 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:
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 for the full design.
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().
const [count, setCount] = createSignal(0);
setCount(1);
count(); // still 0
flush();
count(); // now 1Use 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.
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)
// 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:
// 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:
// 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:
// 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):
// 1.x
onMount(() => {
measureLayout();
});
// 2.0
onSettled(() => {
measureLayout();
const onResize = () => measureLayout();
window.addEventListener("resize", onResize);
return () => window.removeEventListener("resize", onResize);
});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, ...):
// 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.
These are dev-only diagnostics meant to catch bugs earlier. Some are warnings (console); others are errors (throw). See RFC 08 for the full reference.
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.
// ❌ 2.0 warns (top-level reactive read)
function Bad(props) {
const n = props.count;
return <div>{n}</div>;
}
// ✅ read inside JSX/expression
function Ok(props) {
return <div>{props.count}</div>;
}// ❌ 2.0 warns (common: destructuring in args)
function BadArgs({ title }) {
return <h1>{title}</h1>;
}
// ✅ keep props object, or destructure inside a memo/effect
function OkArgs(props) {
return <h1>{props.title}</h1>;
}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)
// ❌ 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.
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:
// 1.x
<Component value={/*@once*/ props.value} />
// 2.0: keep reactive values reactive
<Component value={props.value} />For DOM initial/default state, use the platform default prop instead of freezing a reactive value:
// 1.x
<input value={/*@once*/ props.initialValue} />
// 2.0
<input defaultValue={props.initialValue} />If you truly need the old “read this once” behavior, the replacement is untrack in JavaScript, outside 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.
// 1.x
<Suspense fallback={<Spinner />}>
<Profile />
</Suspense>
// 2.0
<Loading fallback={<Spinner />}>
<Profile />
</Loading>The basic pattern: replace createResource with an async createMemo (or createStore(fn) for collections), and wrap consumers in Loading:
// 1.x
const [user] = createResource(id, fetchUser);
// 2.0
const user = createMemo(() => fetchUser(id()));<Loading fallback={<Spinner />}>
<Profile user={user()} />
</Loading>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) |
See RFC 05 — createResource migration for detailed before/after examples of each pattern.
Loading: initial “not ready yet” UI boundary.isPending(fn): active pending read for the exact expression infn—truewhile a value change is in flight for it (an input changed, or in-flight work declared it withaffects); a barerefresh()/poll of the same inputs is silent. When the expression can be not ready, place it under theLoadingboundary that should own initial fallback UI. It can live outside the boundary when it only reads upstream state that cannot be not ready.
const listPending = () => isPending(() => users() || posts());
<Loading fallback={<Spinner />}>
<Show when={listPending()}>{/* subtle "updating…" indicator while a new query loads */}</Show>
<List users={users()} posts={posts()} />
</Loading>;const latestId = () => latest(id);// After a server write, explicitly recompute a derived read:
refresh(storeOrProjection);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/createOptimisticStorefor optimistic UI - call
refresh(...)at the end to reconcile derived reads with the source of truth
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);
});// 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 aboveconst plain = snapshot(store);
JSON.stringify(plain);// 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”.
const merged = merge({ a: 1, b: 2 }, { b: undefined });
// merged.b is undefined// 1.x
const [local, rest] = splitProps(props, ["class", "style"]);
// 2.0
const rest = omit(props, "class", "style");createSignal(fn) creates a writable derived signal (think “writable memo”):
const [count, setCount] = createSignal(0);
const [doubled] = createSignal(() => count() * 2);createStore(fn, seed) creates a derived store using the familiar createStore API:
const [items] = createStore(() => api.listItems(), []);
const [cache] = createStore(
draft => {
draft.total = items.length;
},
{ total: 0 }
);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 directIndexreplacement.keyed={(item) => key}receives item and index accessors.
// 1.x
<Index each={items()}>
{(item, i) => <Row item={item()} index={i} />}
</Index>
// 2.0
<For each={items()} keyed={false}>
{(item, i) => <Row item={item()} index={i} />}
</For>Prefer literal keyed modes for function children. A dynamic boolean keyed={condition()} makes the callback shape ambiguous.
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}:
<Show when={user()} fallback={<Login />}>
{u => <Profile user={u()} />}
</Show>
<Switch>
<Match when={route() === "profile"}>{() => <Profile />}</Match>
</Switch>createDynamic(source, props): JSX.Element is replaced by a lazy-style factory, dynamic(source): Component<P>. 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.
// 1.x style
import { Dynamic } from "solid-js/web";
<Dynamic component={isEditing() ? Editor : Viewer} value={value()} />;
// 2.0 — hoist a factory; use it like any component
import { dynamic } from "@solidjs/web";
const Active = dynamic(() => (isEditing() ? Editor : Viewer));
return <Active value={value()} />;Async sources compose with Loading/Suspense through the normal NotReadyError flow — no wrapper primitive or await in user code.
<Dynamic component={...}> 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 <For> callback the callback body is the place. Direct callers of the old createDynamic(source, props) compose manually as createComponent(dynamic(source), props).
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.
// 1.x
<SuspenseList revealOrder="forwards">
<Suspense fallback={<Skeleton />}><ProfileHeader /></Suspense>
<Suspense fallback={<Skeleton />}><Posts /></Suspense>
</SuspenseList>
// 2.0 — default sequential ordering
<Reveal>
<Loading fallback={<Skeleton />}><ProfileHeader /></Loading>
<Loading fallback={<Skeleton />}><Posts /></Loading>
</Reveal>
// 2.0 — reveal the whole group at once
<Reveal order="together">
<Loading fallback={<Skeleton />}><ProfileHeader /></Loading>
<Loading fallback={<Skeleton />}><Posts /></Loading>
</Reveal>
// 2.0 — nested natural group that reveals independently within its slot
<Reveal>
<Loading fallback={<Skeleton />}><Header /></Loading>
<Reveal order="natural">
{/* Held on their fallbacks until the outer frontier reaches this slot.
Once released, each card reveals as its own data resolves. */}
<Loading fallback={<CardSkel />}><Card id={1} /></Loading>
<Loading fallback={<CardSkel />}><Card id={2} /></Loading>
</Reveal>
</Reveal>Note: in earlier 2.0 betas
Revealexposed a booleantogetherprop. That prop has been replaced byorder="together".collapsedstill exists; it is a sequential-only knob and has no effect underorder="together"ororder="natural".
Nesting semantics, the outer/inner ordering matrix, and SSR caveats are documented in Control flow → Reveal.
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:, andon: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.
<video muted={true} />
<video muted={false} />
// When the platform really wants a string:
<some-element enabled="true" />Event handlers are camelCase only: on followed by an uppercase letter (onClick, onPointerDown). Lowercase on* names are attributes in 2.0. In 1.x <button onclick={handler}> bound an event like onClick; in 2.0 it sets the onclick attribute (stringifying a function into it), in the browser, in SSR output, and through spreads. Rename lowercase handlers to camelCase:
// 1.x
<button onclick={increment} />
// 2.0
<button onClick={increment} />A string value is now exactly the HTML inline-handler attribute (<link rel="preload" onload="this.rel='stylesheet'">). In development a function passed to a lowercase on* attribute warns with LOWERCASE_EVENT_ATTRIBUTE.
on: and oncapture: are removed. Keep using camelCase event handlers like onClick for Solid-managed events. A leftover on:click={fn} on a native element is a compile error. Through a spread the compiler can't see it, so it becomes a plain (namespaced) attribute and warns in development like a lowercase on* name. For native listener options, use a ref callback:
const on = (type, handler, options) => el => el.addEventListener(type, handler, options);
<button ref={on("click", handleClick, { capture: true })} />;Delegated events are now owned by render roots. render() and hydrate() install delegated listeners on their root container and clean them up when that root is disposed; compiler-emitted delegateEvents([...]) only declares which event names are needed. This replaces the old document-global cleanup model.
For most apps this is automatic. The visible differences are in nested roots, portals, and web component hosts:
- Nested Solid roots no longer synthesize delegated handlers across each other's root boundaries.
- Rendering into a
ShadowRootscopes delegated handlers to that shadow root, which is friendlier to web components. Portalregisters outside-root mount points as listener containers for the owning render root, so portal events still bubble through the logical Solid tree. Portal mounts already inside the root do not install extra listeners.- If you were calling
clearDelegatedEvents(), remove it. Dispose the render root instead.
In Solid 1.x, a ref callback ran inside the reactive owner of the component that declared the ref, so getOwner() was available and cleanup could be registered inline:
// 1.x — the ref callback ran owned, so cleanup could live inside it
<div
ref={el => {
el.addEventListener("pointerdown", onDown);
onCleanup(() => el.removeEventListener("pointerdown", onDown));
}}
/>In Solid 2.0, ref callbacks are unowned — getOwner() returns null inside them. This makes plain refs consistent with the apply phase of directive factories (below): the callback's only job is to capture or touch the element. Lifecycle work belongs in an owned scope, in one of two packagings.
For one-off, component-local behavior, use onSettled in the component body — it runs after render settles (the ref has been assigned by then) and its returned cleanup fires on disposal:
// 2.0 — setup + teardown together in the owned component scope
let el;
onSettled(() => {
el.addEventListener("pointerdown", onDown);
return () => el.removeEventListener("pointerdown", onDown);
});
<div ref={el} />;For reusable behavior, use a directive factory: its setup half runs owned at component creation — primitives and onCleanup live there — and the returned apply callback (the actual ref) is unowned and only captures the element:
function tooltip(options) {
let el;
const instance = createTooltipInstance();
createEffect(
() => options.content,
content => el && instance.setContent(content)
);
onCleanup(() => instance.destroy());
return nextEl => {
el = nextEl;
instance.attach(nextEl);
};
}
<button ref={tooltip({ content: "Save" })} />;Note the timing difference: onSettled runs post-settle with the element already in hand, so element work can sit directly inside it; a factory's setup half runs during render before any element exists, so element-dependent work rides the apply callback or an effect.
// 1.x
<button use:tooltip={{ content: "Save" }} />
// 2.0
<button ref={tooltip({ content: "Save" })} />
<button ref={[autofocus, tooltip({ content: "Save" })]} />Two-phase directive factories are recommended (owned setup → unowned apply):
function titleDirective(source) {
// Setup phase (owned): create primitives/subscriptions here.
// Avoid imperative DOM mutation at top level.
let el;
createEffect(source, value => {
if (el) el.title = value;
});
// Apply phase (unowned): DOM writes happen here.
// No new primitives should be created in this callback.
return nextEl => {
el = nextEl;
};
}// 1.x
<div class="card" classList={{ active: isActive(), disabled: isDisabled() }} />
// 2.0
<div class={["card", { active: isActive(), disabled: isDisabled() }]} />// 1.x
const Theme = createContext("light");
<Theme.Provider value="dark">{props.children}</Theme.Provider>;
// 2.0
const Theme = createContext("light");
<Theme value="dark">{props.children}</Theme>;createContext<T>() (no default) is now typed Context<T> — useContext returns T directly and throws ContextNotFoundError at runtime if no Provider is mounted. Drop any useX-with-throw wrapper hooks; they only existed to narrow the type, which is no longer needed.
// 1.x — wrapper exists purely to narrow T | undefined → T
const TodosContext = createContext<TodosCtx>();
const useTodos = () => {
const ctx = useContext(TodosContext);
if (!ctx) throw new Error("missing TodosContext.Provider");
return ctx;
};
// 2.0 — direct call. Type is TodosCtx; throws if no Provider.
const TodosContext = createContext<TodosCtx>();
const [todos, { addTodo }] = useContext(TodosContext);The default form createContext<T>(defaultValue) is unchanged — useContext falls back to defaultValue outside any Provider. Reserved for primitive fallbacks (theme, locale, frozen config); use the default-less form for any context carrying reactive state.
If you genuinely relied on useContext(ctx) returning undefined for a default-less context, either pass an explicit default to createContext or wrap the call in a try/catch. Most existing wrapper hooks were already throwing on undefined, so for them the change is a removal, not a migration.
undefined is never a context value: it means "not provided". createContext<T | undefined>(undefined) is still a default-less context, and a Provider passing value={undefined} counts as no Provider, so both throw ContextNotFoundError (in dev the message names the context and which case it hit). For an optional context, use null as the explicit empty value: createContext<T | null>(null) returns null outside a Provider, and a Provider can pass null too.
These APIs are new additions (not renames of 1.x APIs):
Reveal— coordinates reveal timing of siblingLoadingboundaries via anorderprop ("sequential"|"together"|"natural") plus a sequential-onlycollapsedflag. ReplacesSuspenseList.order="natural"is new: the nested group participates as a single composite slot in its parent's ordering, and once the parent releases that slot, each inner child reveals independently on its own data.Repeat— count/range-based list rendering without diffing (skeletons, windowing).action(fn)— wraps generator/async generator mutations with transition coordination.createOptimistic/createOptimisticStore— signal/store primitives whose writes revert when a transition completes.createProjection(fn, seed)— derived store with reactive reconciliation.isPending(fn)— expression-level "unrevealed change in flight" check.latest(fn)— peek at in-flight values during transitions.refresh(target)— explicit recomputation/invalidation of derived reads (a quiet re-ask — not pending). Returns a promise for the target's next quiescent state: accessors resolve with the settled value, stores with the node passed; a failed re-ask rejects (in an action,yield refresh(x)throws back at the yield point); superseded flights fold onto whatever finally lands. Safe to ignore for fire-and-forget use. See RFC 06.affects(target, key?)— declare that in-flight work will change the targeted data; the marked record (or the single named slot) reads pending until the transaction settles.resolve(fn)— returns a Promise that resolves when a reactive expression settles.until(fn, options?)— returns a Promise that resolves the first time a reactive predicate settles truthy (withtimeout/signalrejection). Yielded from anaction(), it holds the transaction — and its optimistic state — open until arriving truth confirms the mutation (live sockets, subscriptions, live queries, or a refetch the action itself issued). The predicate reads the authoritative view: optimistic overrides are invisible (the action's own tentative writes can never satisfy it), while real data — committed or still staged in the open transaction — reads normally. See RFC 06.Loadingonprop — a dependency list for the boundary: a tracked expression whose value is irrelevant. A change to anything it reads makesLoadingstop waiting on its current content and show its fallback again (if something under it is still pending) instead of keeping stale content through revalidation — the fallback lands with the same frame as the change, immediately when nothing else holds it, with the rest of the new page during a held navigation.deep(store)— deep observation of a store (tracks all nested changes).reconcile(value, key)— diffing function for updating stores from new data.- Function-form
createSignal(fn)/createStore(fn)— derived (writable) primitives. - Effect
EffectBundle—createEffectaccepts{ effect, error }for structured error handling. createMemolazyoption — defers initial computation until first read; also opts the memo into autodisposal when its subscriber count drops to zero. Non-lazy owned memos live for their owner's lifetime.unobservedcallback — fires when a signal/memo loses all subscribers (resource cleanup).dynamic(source)factory —lazy-style factory that returns a stable component whose identity is driven by a reactive (and optionally async) source. ReplacescreateDynamic; the<Dynamic>JSX wrapper is kept but deprecated in its favor.clientOnly(() => import(...), { lazy? })(@solidjs/web, hoisted from SolidStart) — wraps a dynamically imported component so it renders only in the browser: the server rendersprops.fallbackand never starts the import. Unlikelazy(), it avoids Suspense entirely and never server-renders, so it participates in no hydration asset manifest; a mount gate keeps hydration mismatch-free.{ lazy: true }defers the import to first render.httpStatus(code, text?)/httpHeader(name, value, { append? })(@solidjs/web, hoisted from SolidStart) — declare response status/headers during SSR against the request event'sresponsehead for the lifetime of the calling reactive scope. Scope-tied declarations, not mutations: call them bare in component/reactive-scope bodies (including behind anif), and they un-declare on scope disposal. Writes snapshot the prior value and retract it on disposal (a boundary that errors/recovers un-writes rather than stomping to defaults), and both writes and retractions become no-ops once the integration marks the response headcommitted(head derived/sent). No-ops on the client. The primitives are the whole core API — core ships functions only; SolidStart may provide component wrappers for compatibility.ssrSourceoption ("server"|"hybrid"|"client") — per-primitive hydration policy on memos, function-form signals/stores, projections, and effects: whether the client seeds from the serialized server value ("server", default), seeds then continues an async-iterable compute's stream from it ("hybrid"— identical to"server"for sync/promise computes), or skips the server value and computes only after hydration ("client"— the compute never runs on the server). Pairs withdeferStream: true, which holds the SSR stream flush until the primitive's first value resolves (server-only). See RFC 05.renderToStream(...).readable— aResponse-body-readyReadableStream(Uint8Array chunks) alongside the existingpipe/pipeTo; exactly one consumer per render. See RFC 12.
These removals benefit from more context than a one-liner. For simple renames, see the quick map below.
In 1.x, batch was explicit — you wrapped multiple writes to avoid intermediate renders. In 2.0, all writes are batched by default (microtask). There's nothing to wrap. If you need to force synchronous application (tests, imperative interop), use flush():
// 1.x
batch(() => {
setA(1);
setB(2);
});
// 2.0 — just write; batching is automatic
setA(1);
setB(2);
// If you need synchronous "apply now":
setA(1);
setB(2);
flush();createComputed was used for three distinct patterns. The replacement depends on which one:
Readonly derivation — use createMemo:
// 1.x
createComputed(() => setDoubled(count() * 2));
// 2.0
const doubled = createMemo(() => count() * 2);Side effect on change — use split createEffect:
// 1.x
createComputed(() => {
const val = input();
localStorage.setItem("input", val);
});
// 2.0
createEffect(
() => input(),
val => localStorage.setItem("input", val)
);Derived-with-writeback (computed that also has a setter) — use function-form createSignal:
// 1.x
const [value, setValue] = createSignal(props.initial);
createComputed(() => setValue(props.initial));
// 2.0
const [value, setValue] = createSignal(() => props.initial);on existed to declare explicit dependencies separately from the effect body. Split effects make this unnecessary — the compute phase is the explicit dependency declaration:
// 1.x
createEffect(
on(count, (value, prev) => {
console.log("changed from", prev, "to", value);
})
);
// 2.0 — compute phase declares deps, effect phase runs side effects
createEffect(
() => count(),
(value, prev) => {
console.log("changed from", prev, "to", value);
}
);// 1.x — multiple deps
createEffect(
on([a, b], ([a, b]) => {
console.log(a, b);
})
);
// 2.0
createEffect(
() => [a(), b()],
([a, b]) => console.log(a, b)
);on also had a defer option to skip the initial run. In 2.0, createEffect has this directly:
// 1.x
createEffect(
on(
count,
value => {
console.log("changed to", value);
},
{ defer: true }
)
);
// 2.0
createEffect(
count,
value => {
console.log("changed to", value);
},
{ defer: true }
);In 1.x, onError/catchError were imperative error handlers registered in scope. In 2.0, errors propagate through the reactive graph and are caught structurally:
Component-level error UI — use Errored:
// 1.x
<ErrorBoundary fallback={err => <p>{err.message}</p>}>
<Child />
</ErrorBoundary>
// 2.0
<Errored fallback={err => <p>{err().message}</p>}>
<Child />
</Errored>Programmatic error handling in effects — use the error option:
// 1.x
catchError(
() => {
createEffect(() => riskyAsyncWork());
},
err => console.error("caught:", err)
);
// 2.0
createEffect(() => riskyAsyncWork(), {
effect: value => {
/* success path */
},
error: err => console.error("caught:", err)
});produce is not really "removed" — it's the default. Store setters in 2.0 receive a mutable draft. If you imported produce to wrap your setter, just drop it:
// 1.x
import { produce } from "solid-js/store";
setStore(
produce(s => {
s.user.name = "Alice";
s.list.push("item");
})
);
// 2.0 — draft-first is the default
setStore(s => {
s.user.name = "Alice";
s.list.push("item");
});A 1.x path setter maps onto a draft write to the same path — ranges and filters become loops, and setting undefined to remove a key becomes delete:
// 1.x: setStore("user", "name", "Alice")
setStore(s => {
s.user.name = "Alice";
});
// 1.x: setStore("todos", t => t.done, "archived", true)
setStore(s => {
for (const t of s.todos) if (t.done) t.archived = true;
});createMutable gave you a proxy you could write to directly. In 2.0, createStore with draft setters gives the same ergonomics while keeping writes explicit:
// 1.x
const state = createMutable({ count: 0, items: [] });
state.count++;
state.items.push("a");
// 2.0
const [state, setState] = createStore({ count: 0, items: [] });
setState(s => {
s.count++;
s.items.push("a");
});The key difference: writes go through setState, which makes them visible to the reactive system's batching and transition coordination. Direct mutation on a proxy can't participate in transitions or optimistic rollback.
from converted external reactive sources into signals. observable converted signals into observables. These directions have different replacements.
External → Solid (from): from(source) now returns an async iterable, and async iterables are first-class in computations. Return it from a memo:
// 1.x
import { from } from "solid-js";
const signal = from(observable$);
// 2.0 — from() adapts the source; the memo consumes it
import { createMemo, from } from "solid-js";
const value = createMemo(() => from(observable$));from accepts a subscribe function ((next, error, complete) => unsubscribe; unlike 1.x's set, next stores what it's given, so a 1.x producer calling set(prev => ...) must compute the value itself), an Observable (anything with subscribe(observer), including Symbol.observable / "@@observable" interop such as RxJS), or an async iterable. A subscription keeps only the latest value: values that arrive before the memo pulls again coalesce. A value the source emits during subscribe (a BehaviorSubject, say) shows on the first render, with no loading frame. An async iterable streams every value through. Errors reach the nearest Errored boundary.
The source closes as soon as the memo re-runs (for example, when a source it reads changes), or when its owner is disposed. It doesn't wait for the new source's first value.
Under SSR, from follows the memo's ssrSource:
- A subscription or Observable counts as a live source: each value is the whole current state. With the default
ssrSource, the server renders and serializes its first value, then unsubscribes. The client adopts that value while hydrating, then subscribes again once its section has hydrated. A source that never emits can't hold the response open."hybrid"behaves the same on the server, but the client treats its first new value as a repeat of the server's and drops it, so use it only with a source that replays its current value on subscribe. With"client", the server never subscribes. - An async iterable streams like any other: with the default
ssrSource, the server renders the first value and streams the rest to the client until the source ends. A source that never ends keeps the response open until the client disconnects. Return a subscription instead, or use"hybrid"(the server takes one value) or"client".
Either way the server releases the source when it stops reading it, or when the render is disposed.
An async iterable can also be consumed directly in an async generator:
const value = createMemo(async function* () {
for await (const val of iterable) {
yield val;
}
});Here cleanup is not immediate. When the owner is disposed, or a re-run replaces the stream, Solid calls the generator's return(), but a generator waiting at an await can't finish until that await settles. The source stays subscribed until it produces another value or ends. from is the exception, as long as the for await starts before the generator's first await: a from(source) iterated there still closes its source immediately on a re-run (from(iterable) calls the iterable's return() immediately; an async generator source still finishes its own pending await first, but its values no longer reach the memo). After an await the generator has no owner, so a from iterated there closes only when the loop ends, like any other source. Even so, prefer returning from(source) directly (read awaited inputs from an upstream memo) and doing transforms in a downstream memo (createMemo(() => format(value()))) rather than in the loop body: the loop may run once more after a re-run, as the closed source ends the loop.
Solid → External (observable): There's no drop-in replacement. observable() produced a standard Observable that external libraries could subscribe to. In 2.0, use createEffect to push signal changes to an external subscriber:
// 1.x
import { observable } from "solid-js";
const obs$ = observable(signal);
obs$.subscribe(value => externalLib.update(value));
// 2.0 — use an effect to push changes outward
createEffect(signal, value => {
externalLib.update(value);
});If you need a standard Observable/AsyncIterable interface for external consumers, you'll need to build a thin adapter around createEffect. This is a known gap — the 1.x observable() convenience doesn't have a direct 2.0 equivalent yet. I expect this to move into @solid-primitives.
solid-js/web→@solidjs/websolid-js/store→solid-js(store APIs now exported fromsolid-jsdirectly)solid-js/h→@solidjs/hsolid-js/html→@solidjs/htmlsolid-js/universal→@solidjs/universaljsxImportSource: "solid-js"→"@solidjs/web"for web JSX ("@solidjs/h"for hyperscript JSX)
Suspense→LoadingSuspenseList→RevealErrorBoundary→ErroredmergeProps→mergesplitProps→omitcreateSelector→createProjection/createStore(fn)createDynamic(source, props)/<Dynamic component>→dynamic(source)factory (<Dynamic>deprecated but kept in 2.0)unwrap→snapshotonMount→onSettledequalFn→isEqualgetListener→getObserverclassList→class(object/array forms)
createResource→ async computations +LoadingstartTransition/useTransition→ built-in transitions +isPending/Loading+ optimistic APIsbatch→flush()when you need synchronous applicationcreateComputed→createEffect(split), function-formcreateSignal/createStore, orcreateMemoonhelper → no longer necessary with split effectsonError/catchError→Erroredor effecterroroptionproduce→ now the default store setter behavior (draft-first)createMutable/modifyMutable→ usecreateStorewith draft settersfrom→ still exported, but returns an async iterable for a memo:createMemo(() => from(source))observable→createEffectpushing to the external subscribercreateDeferred→ same name, new meaning: an async memo that may lag but never leads (keeps its last answer while a refetch is in flight;isPendingreports the refetch). 1.x's idle-time deferral andtimeoutMsare gone; with a synchronous function it behaves likecreateMemoindexArray→ usemapArraywithkeyed: falseresetErrorBoundaries→ no longer needed (error boundaries heal automatically)enableScheduling→ removedwriteSignal→ removed (internal API that should not have been exported)sharedConfig/$DEVCOMP→ no longer part ofsolid-js's public types; renderers and tooling reach them throughsolid-js/internal(not public API — no semver guarantee, may change in any release)use:directives →refdirective factoriesattr:/bool:namespaces → standard attribute behavioron:/oncapture:→onClickfor Solid events; ref callbacks for native listener optionsContext.Provider→ use the context directly as provider (<Context value={...}>)solid-js/jsx-runtime/solid-js/jsx-dev-runtime→ renderer runtime entries such as@solidjs/web/jsx-runtime