Skip to content

Latest commit

 

History

History
1100 lines (825 loc) · 46.3 KB

MIGRATION.md

File metadata and controls

1100 lines (825 loc) · 46.3 KB

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 <Loading> 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 <For keyed={false}>. 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.

// 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";

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:

{
  "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.

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().

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)
// 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);
});

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, ...):

// 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.

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 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.

// ❌ 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>;
}

“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)
// ❌ 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:

// 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.

Async data & transitions

Suspense / ErrorBoundary → Loading / Errored

// 1.x
<Suspense fallback={<Spinner />}>
  <Profile />
</Suspense>

// 2.0
<Loading fallback={<Spinner />}>
  <Profile />
</Loading>

createResource → async computations + 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.

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.
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>;

Peeking in-flight values: latest(fn)

const latestId = () => latest(id);

“Refetch/refresh” patterns → refresh()

// 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
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

// 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)

const plain = snapshot(store);
JSON.stringify(plain);

mergeProps / splitProps → merge / omit

// 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");

New function forms: createSignal(fn) and createStore(fn)

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 }
);

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.
// 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.

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}:

<Show when={user()} fallback={<Login />}>
  {u => <Profile user={u()} />}
</Show>

<Switch>
  <Match when={route() === "profile"}>{() => <Profile />}</Match>
</Switch>

Dynamic components: createDynamic / <Dynamic> → dynamic factory

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).

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.

// 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 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.

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.

<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 ShadowRoot scopes delegated handlers to that shadow root, which is friendlier to web components.
  • Portal registers 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.

Ref callbacks: no longer owned

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.

Directives: use: → ref directive factories (two-phase pattern)

// 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;
  };
}

classList → class (object/array forms)

// 1.x
<div class="card" classList={{ active: isActive(), disabled: isDisabled() }} />

// 2.0
<div class={["card", { active: isActive(), disabled: isDisabled() }]} />

Context

Context providers: Context.Provider → “context is the provider”

// 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>;

useContext on a default-less context returns T, not T | undefined

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.

New in 2.0

These APIs are new additions (not renames of 1.x APIs):

  • Reveal — coordinates reveal timing of sibling Loading boundaries via an order prop ("sequential" | "together" | "natural") plus a sequential-only collapsed flag. Replaces SuspenseList. 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 (with timeout/signal rejection). Yielded from an action(), 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.
  • Loading on prop — a dependency list for the boundary: a tracked expression whose value is irrelevant. A change to anything it reads makes Loading stop 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 — createEffect accepts { effect, error } for structured error handling.
  • createMemo lazy option — 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.
  • unobserved callback — 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. Replaces createDynamic; 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 renders props.fallback and never starts the import. Unlike lazy(), 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's response head for the lifetime of the calling reactive scope. Scope-tied declarations, not mutations: call them bare in component/reactive-scope bodies (including behind an if), 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 head committed (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.
  • ssrSource option ("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 with deferStream: true, which holds the SSR stream flush until the primitive's first value resolves (server-only). See RFC 05.
  • renderToStream(...).readable — a Response-body-ready ReadableStream (Uint8Array chunks) alongside the existing pipe/pipeTo; exactly one consumer per render. See RFC 12.

Detailed removal guide

These removals benefit from more context than a one-liner. For simple renames, see the quick map below.

batch → default microtask batching + flush()

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 → createMemo, createEffect, or derived createSignal

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 helper → split effects

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 }
);

onError / catchError → Errored + effect error option

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 → now the default setter behavior

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 / modifyMutable → createStore with draft setters

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 / observable → from returns an async iterable / effects

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.

Quick rename / removal map

Import paths

  • solid-js/web → @solidjs/web
  • solid-js/store → solid-js (store APIs now exported from solid-js directly)
  • solid-js/h → @solidjs/h
  • solid-js/html → @solidjs/html
  • solid-js/universal → @solidjs/universal
  • jsxImportSource: "solid-js" → "@solidjs/web" for web JSX ("@solidjs/h" for hyperscript JSX)

Renames

  • Suspense → Loading
  • SuspenseList → Reveal
  • ErrorBoundary → Errored
  • mergeProps → merge
  • splitProps → omit
  • createSelector → createProjection / createStore(fn)
  • createDynamic(source, props) / <Dynamic component> → dynamic(source) factory (<Dynamic> deprecated but kept in 2.0)
  • unwrap → snapshot
  • onMount → onSettled
  • equalFn → isEqual
  • getListener → getObserver
  • classList → class (object/array forms)

Removals

  • createResource → async computations + Loading
  • startTransition / useTransition → built-in transitions + isPending/Loading + optimistic APIs
  • batch → flush() when you need synchronous application
  • createComputed → createEffect (split), function-form createSignal/createStore, or createMemo
  • on helper → no longer necessary with split effects
  • onError / catchError → Errored or effect error option
  • produce → now the default store setter behavior (draft-first)
  • createMutable / modifyMutable → use createStore with draft setters
  • from → still exported, but returns an async iterable for a memo: createMemo(() => from(source))
  • observable → createEffect pushing to the external subscriber
  • createDeferred → same name, new meaning: an async memo that may lag but never leads (keeps its last answer while a refetch is in flight; isPending reports the refetch). 1.x's idle-time deferral and timeoutMs are gone; with a synchronous function it behaves like createMemo
  • indexArray → use mapArray with keyed: false
  • resetErrorBoundaries → no longer needed (error boundaries heal automatically)
  • enableScheduling → removed
  • writeSignal → removed (internal API that should not have been exported)
  • sharedConfig / $DEVCOMP → no longer part of solid-js's public types; renderers and tooling reach them through solid-js/internal (not public API — no semver guarantee, may change in any release)
  • use: directives → ref directive factories
  • attr: / bool: namespaces → standard attribute behavior
  • on: / oncapture: → onClick for Solid events; ref callbacks for native listener options
  • Context.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