docs: add Solid 2.0 beta migration guide

Add a beta tester-focused migration guide and topic deep-dives under documentation/solid-2.0.

Made-with: Cursor

Author: ryansolid

documentation/solid-2.0/01-reactivity-batching-effects.md

@@ -0,0 +1,158 @@
+# RFC: Reactivity, batching, and effects
+
+**Start here:** If you’re migrating an app, read the beta tester guide first: [MIGRATION.md](MIGRATION.md)
+
+## Summary
+
+Solid 2.0 tightens the reactivity model: no writes under owned scope (with narrow exceptions), stricter use of `untrack` for top-level reactive reads, and microtask batching via `flush` instead of `batch`. Effects are split into a tracking phase and an effect phase, enabling safer async and resumability. `createTrackedEffect` and `onSettled` (replacing `onMount`) complete the picture. These changes make the execution model predictable and allow Loading/Error boundaries to work correctly with async.
+
+## Motivation
+
+- **Writes under scope:** Writing to a signal inside a tracked context (e.g. inside an effect or component body) can cause subtle bugs and makes the graph harder to reason about. Split effects make it safe to disallow this by default.
+- **Strict top-level access (new):** Top-level reactive reads in component body can accidentally capture dependencies and re-run in async situations; in 2.0 we warn in dev unless the read is inside createMemo/createEffect or explicit `untrack`.
+- **Batching:** Synchronous batching with `batch()` is replaced by default microtask batching; the graph is immediately “askable” after a set, but DOM updates are deferred until the next microtask (or until `flush()`). This aligns with Vue/Svelte and simplifies the model; `batch` is no longer needed.
+- **Split effects:** Running all “tracking” (compute) halves of effects before any “effect” (callback) halves gives a clear dependency picture before side effects run, which is required for async, Loading, and Errored boundaries.
+
+## Detailed design
+
+### No writes under owned scope
+
+Writing to a signal inside a reactive scope (effect, memo, component body) warns in dev. Writes belong in event handlers, `onSettled`, or untracked blocks. When a signal must be written from within scope (e.g. internal state), opt in with `pureWrite: true`:
+
+```js
+// Default: warn if set in effect/component
+const [count, setCount] = createSignal(0);
+
+// Opt-in: allow writes in owned scope (e.g. internal flags)
+const [ref, setRef] = createSignal(null, { pureWrite: true });
+```
+
+`pureWrite` is not a general-purpose escape hatch. A common misuse is enabling it to silence warnings for application state while still writing from reactive scope:
+
+```js
+// ❌ BAD: using pureWrite to silence a write-under-scope warning for app state
+const [count, setCount] = createSignal(0, { pureWrite: true });
+const [doubled, setDoubled] = createSignal(untrack(count) + 1); // force untracked read to get around other warning
+createMemo(() => setDoubled(count() + 1)); // feedback loop
+
+// ✅ GOOD: derive without writing back, or write in an event
+const doubled = createMemo(() => count() * 2);
+button.onclick = () => setCount((c) => c + 1);
+```
+
+### Strict top-level access (new in 2.0)
+
+**What’s new:** In component body **top level**, reactive reads (signal, signal-backed prop, store property) **warn in dev** unless they are inside a reactive scope (e.g. `createMemo`, `createEffect`) or explicitly wrapped in `untrack`. This steers authors to avoid accidental dependencies that would re-run the component in async or lose reactivity.
+
+```js
+// New: top-level read in component body warns unless wrapped
+function Title(props) {
+  const t = untrack(() => props.title); // intentional one-time read — no warn
+  return <h1>{t}</h1>;
+}
+function Bad(props) {
+  const t = props.title; // warns: Untracked reactive read
+  return <h1>{t}</h1>;
+}
+
+// Common pitfall: destructuring reactive props at top level (warns)
+function BadArgs({ title }) {
+  return <h1>{title}</h1>;
+}
+```
+
+This also applies to the **bodies of control-flow function children** (e.g. Show/Match/For callbacks): those callbacks are structure-building, so reactive reads done directly in the callback body won’t update and will warn in dev. Prefer reading through JSX expressions (which compile to tracked computations), or wrap the read in a reactive scope.
+
+```js
+// ❌ BAD: reactive read in callback body (warns)
+<Show when={user()}>
+  {(u) => {
+    const name = u().name;
+    return <span>{name}</span>;
+  }}
+</Show>
+
+// ✅ GOOD: read in JSX expression (tracked)
+<Show when={user()}>{(u) => <span>{u().name}</span>}</Show>
+```
+
+Tests: `packages/solid/test/component.spec.ts` ("Strict Read Warning") — warns on direct signal read, props backed by signal, store destructuring; no warn inside createMemo, createEffect, or untrack.
+
+Derived signals should not initiate other signals from reactive values except through the derived (initializer) form.
+
+### `flush` and microtask batching
+
+Updates are applied on the next microtask by default: the graph is readable immediately after a set, but DOM and effect callbacks run later. Use **`flush()`** when you need to read the DOM right after a state change (e.g. focus):
+
+```js
+function handleSubmit() {
+  setSubmitted(true);
+  flush(); // apply updates now
+  inputRef.focus(); // DOM is up to date
+}
+```
+
+**`batch` is removed;** `flush()` is the way to synchronously apply pending updates.
+
+### Split tracking from effect
+
+Effects have two phases: **compute** (reactive reads only; dependencies recorded) and **effect** (side effects; runs after all compute phases in the batch). This gives a clear dependency picture before any side effects run and is required for async and boundaries.
+
+```js
+createEffect(
+  () => count(),           // compute: only reads
+  (value, prev) => {       // effect: runs after flush
+    console.log(value);
+    return () => { /* cleanup */ };
+  }
+);
+
+// With initial value
+createEffect(
+  () => [a(), b()],
+  (deps) => { /* ... */ },
+  undefined
+);
+```
+
+**`createRenderEffect`** is split the same way and tears when dependencies change. **`createEffect`** may accept an options object with `effect` and `error` for handling errors from the reactive graph (e.g. async).
+
+### createTrackedEffect and onSettled
+
+**`createTrackedEffect`** is the single-callback form for special cases; it may re-run in async situations and is not the default. **`onSettled`** replaces `onMount`: run logic when the current activity is settled (e.g. after mount, or from an event handler to defer work until the reactive graph is idle).
+
+```js
+onSettled(() => {
+  const value = count(); // reactive read allowed here
+  doSomething(value);
+  return () => cleanup();
+});
+```
+Unlike other tracked scopes these primitives cannot create nested primitives which is a breaking change from Solid 1.x. They also return a cleanup function instead of their previous value.
+
+**`onCleanup`** remains for reactive lifecycle cleanup inside computations. But is not expected to be used inside side effects.
+
+## Migration / replacement
+
+- **`batch`:** Remove; use `flush()` when you need synchronous application of updates (e.g. before reading DOM).
+- **`onMount`:** Replace with `onSettled`.
+- **Writes under scope:** Move setter calls to event handlers, `onSettled`, or untracked blocks; or create the signal with `{ pureWrite: true }` for the rare valid case (e.g. internal or intentionally in-scope writes).
+
+## Removals
+
+| Removed | Replacement / notes |
+|--------|----------------------|
+| `batch` | `flush()` when you need immediate application |
+| `onError` / `catchError` | Effect `error` callback or ErrorBoundary / Errored |
+| `on` helper | No longer necessary with split effects |
+
+`@solidjs/legacy` can provide approximations for deprecated APIs where feasible.
+
+## Alternatives considered
+
+- Keeping `batch` as an alias for “run updates now” was considered; unifying on `flush` reduces API surface and matches the mental model (drain queue).
+- Keeping a single-callback effect as the default was rejected in favor of split effects for async and boundary semantics.
+
+## Open questions
+
+- Whether to promote the write-under-scope warning to an error in a future release.

documentation/solid-2.0/02-signals-derived-ownership.md

@@ -0,0 +1,141 @@
+# RFC: Signals, derived primitives, ownership, and context
+
+**Start here:** If you’re migrating an app, read the beta tester guide first: [MIGRATION.md](MIGRATION.md)
+
+## Summary
+
+This RFC groups the “core runtime ergonomics” changes that are tightly coupled: **ownership defaults**, **context provider ergonomics**, and **derived (function-form) primitives**. The goal is to make reactive lifetime more predictable (fewer unowned graphs), reduce API surface (`Context.Provider`, `createComputed`), and make “derived state” patterns use consistent primitives with clearer semantics.
+
+## Motivation
+
+- **Ownership as the default:** In 1.x it’s easy to accidentally create unowned reactive graphs (especially in library code), which leads to leaks and confusing cleanup. In 2.0 we want ownership to be the default and detaching to be explicit.
+- **Context ergonomics:** `Context.Provider` is boilerplate and a special-case surface. Using the context value directly as the provider component reduces ceremony and aligns with how it’s used.
+- **Derived primitives:** Patterns that previously relied on `createComputed` (or ad-hoc “write-back” computations) should move to primitives that are composable with async and with split effects. “Function-form” `createSignal` / `createStore` offer a single consistent place for “derived but writable” shapes.
+
+## Detailed design
+
+### Ownership: `createRoot` is owned by the parent by default
+
+In 2.0, a root created inside an existing owned scope is itself owned by that parent (and will be disposed when the parent is disposed). You still get a `dispose` callback for manual cleanup.
+
+```js
+function Widget() {
+  createRoot((dispose) => {
+    const [count, setCount] = createSignal(0);
+    const id = setInterval(() => setCount((c) => c + 1), 1000);
+    onCleanup(() => clearInterval(id));
+  });
+  return null;
+}
+// When Widget is disposed, the nested root is disposed too.
+```
+
+#### Detaching is explicit: `runWithOwner(null, ...)`
+
+If you really want “no owner” (module singletons, external integrations), detach explicitly:
+
+```js
+// A truly detached singleton
+export const singleton = runWithOwner(null, () => {
+  const [value, setValue] = createSignal(0);
+  return { value, setValue };
+});
+```
+
+This makes “global lifetime” an explicit opt-in rather than the accidental default.
+
+### Context: context value is the provider component
+
+Context creation still looks the same, but usage becomes simpler: the context itself is a component that takes a `value` prop and provides it to descendants.
+
+```js
+// 2.0
+const ThemeContext = createContext("light");
+
+function App() {
+  return (
+    <ThemeContext value="dark">
+      <Page />
+    </ThemeContext>
+  );
+}
+
+function Page() {
+  const theme = useContext(ThemeContext);
+  return <div class={theme}>...</div>;
+}
+```
+
+### Derived primitives: function-form `createSignal` and `createStore`
+
+2.0 supports function overloads for `createSignal` and `createStore` to represent “derived state” using the same primitives users already know.
+
+#### Function-form `createSignal` (“writable memo”)
+
+`createSignal(fn, initialValue?, options?)` creates a signal whose value is computed by `fn(prev)` and can also be written through its setter. This replaces many `createComputed` “write-back” use cases with an explicit primitive.
+
+```js
+// Example: derived signal
+const [value, setValue] = createSignal(() => props.something);
+// setValue(...) writes like a normal signal; the compute receives prev on recompute.ß
+```
+
+#### Function-form `createStore` (derived/projection store)
+
+`createStore(fn, initial?, options?)` creates a derived store driven by mutation in `fn(draft)` (and may also return a value / Promise / async iterable). It’s the store analogue for derived shapes and underpins patterns like “selector-like” updates without notifying everything.
+
+```js
+// Example: derived store that only flips the active key
+const [selected, setSelected] = createStore((draft) => {
+  const id = selectedId();
+  draft[id] = true;
+  if (draft._prev != null) delete draft[draft._prev];
+  draft._prev = id;
+}, {});
+```
+
+## Migration / replacement
+
+### `Context.Provider` → context-as-provider
+
+```jsx
+// 1.x
+<ThemeContext.Provider value="dark">
+  <Page />
+</ThemeContext.Provider>
+
+// 2.0
+<ThemeContext value="dark">
+  <Page />
+</ThemeContext>
+```
+
+### Unowned roots → explicit detachment
+
+- If you relied on roots living “forever,” wrap them in `runWithOwner(null, ...)`.
+- Otherwise, prefer creating roots under an existing owner so disposal is automatic.
+
+### `createComputed` removal
+
+If you used `createComputed` to “write back”:
+
+- Prefer split `createEffect(compute, effect)` (RFC 01) when the intent is “react to X and do side effects”.
+- Prefer function-form `createSignal` / `createStore` when the intent is “derived state with a setter”.
+- Prefer `createMemo` for readonly derived values.
+
+## Removals
+
+| Removed | Replacement |
+|--------|-------------|
+| `createComputed` | `createEffect` (split), function-form `createSignal`/`createStore`, or `createMemo` |
+| `Context.Provider` | Use the context directly as the provider component (`<Context value={...}>`) |
+
+## Alternatives considered
+
+- Keeping `createRoot` detached by default: rejected because it makes leaks and “forever lifetime” accidental.
+- Keeping `Context.Provider`: rejected as needless boilerplate and special casing.
+- Keeping `createComputed`: rejected because “write-back computations” are harder to reason about in an async/split-effects model.
+
+## Open questions
+
+- Should we provide an explicit “detached root” helper (sugar over `runWithOwner(null, ...)`) for readability?