Skip to content

Commit 80bb890

Browse files
committed
docs: note that refs run before attachment, and that stores ignore later mutation of the objects passed in
1 parent e321b90 commit 80bb890

3 files changed

Lines changed: 6 additions & 0 deletions

File tree

‎documentation/solid-2.0/04-stores.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,8 @@ setStore(s => {
167167

168168
This pairs naturally with `createProjection`, where returning a value from the derive function uses reconciliation automatically (keyed by `options.key`, default `"id"`).
169169

170+
Don't keep mutating an object after handing it to a store. A later in-place change to that object isn't observed, and assigning or reconciling the same object again doesn't pick it up either, because the store sees the same reference. Pass a fresh object instead (a new response, or a copy such as `{ ...next }`). This mostly affects test fixtures and caches that reuse one response object.
171+
170172
### Shallow stores (`shallow: true`)
171173

172174
By default stores track at property level all the way down — that is the model, and it is the right choice for almost all state. `shallow: true` is a **specialized performance opt-in** for one identifiable workload shape, not a general recommendation: reach for it when profiling shows ingestion cost on data whose records change wholesale.

‎documentation/solid-2.0/07-dom.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ let el;
9393
<div ref={[node => (el = node), autofocus]} />; // assigned
9494
```
9595

96+
A ref runs before the element is inserted into the page. At that point `el.isConnected` is `false`, and `el.ownerDocument` is the inert document of the template the element was cloned from, so `el.ownerDocument.defaultView` is `null`. Don't reach the window or document through the element inside a ref: use the global `window`/`document`, or do work that needs the attached element (measuring, reading computed styles) in `onSettled`.
97+
9698
#### Two-phase directive factories (owned setup, unowned application)
9799

98100
The recommended directive pattern is **two-phase**, similar in spirit to “split effects” (compute phase vs apply phase):

‎packages/solid/CHEATSHEET.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -447,6 +447,8 @@ hydrate(() => <App />, document.getElementById("root")!);
447447
<button ref={[autofocus, tooltip({ content: "Save" })]} />
448448
```
449449

450+
A ref runs before the element is attached: `el.isConnected` is `false` and `el.ownerDocument.defaultView` is `null`. Use the global `window`/`document`, or do layout-dependent work in `onSettled`.
451+
450452
Two-phase directive (recommended):
451453

452454
```ts

0 commit comments

Comments
 (0)