Skip to content

Commit 17d4d1b

Browse files
ryansolidclaude
andauthored
docs: onFlush and the hydration tracking run in the skill and cheatsheet; cached import() note (#4332) (#4335)
- solid-2.0 skill: land a write on its own with onFlush; never cache a promise or import() created inside a compute (hydration's tracking run). - CHEATSHEET: onFlush import and example; hydration adopts server answers, a hydrated Errored keeps the server fallback, no promise caches in computes. - 05-async-data: a cached dynamic import() under Vite's __vitePreload is the fake Promise too (#4332). - babel-plugin README: runs on @babel/core 7.20.12+ and 8. Claude-Session: https://claude.ai/code/session_0117BoWLQXHbGurmfMSCBeKX Co-authored-by: Claude <[email protected]>
1 parent ac28157 commit 17d4d1b

4 files changed

Lines changed: 28 additions & 1 deletion

File tree

‎documentation/solid-2.0/05-async-data.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,8 @@ const user = createMemo(() => {
269269
// `Promise.resolve(value)` inside the compute is the fake too, and never settles either.
270270
```
271271
272+
A cached dynamic `import()` hangs the same way ([#4332](https://github.com/solidjs/solid/issues/4332)). In a Vite build every `import()` goes through `__vitePreload`, which starts from `Promise.resolve()` read off the global at call time, so the module promise stored in a de-duplication map during the tracking run is the fake. The memo itself hydrates from the server's value, so the page looks right; the next caller that hits the map (a later mount, a navigation) waits forever and no request for the chunk is made. Use `lazy()` for components (it already refuses to cache a load made during a trace), and keep a module cache out of hydrated computes or apply the rule below.
273+
272274
The rule for a cache seeded from hydration data: while `isHydrating()` (`solid-js`) is true, treat the seeded value as fresh, and do not populate the cache by running the fetcher. To wrap a hydrated value in a real promise, capture the constructor at module load. The fakes only replace the global inside the window.
273275
274276
```js

‎packages/babel-plugin/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Solid 2.0's Babel compiler integration. Configure this plugin once in a Babel pi
44

55
The native Oxc compiler — [`@solidjs/compiler`](../compiler) — is the default in `vite-plugin-solid`. Use this plugin when you need a Babel pipeline (or as the JavaScript fallback).
66

7+
It runs on `@babel/core` 7 (7.20.12 or later) and 8.
8+
79
> **Solid 2.0 (Release Candidate).** Pin exact versions.
810
911
## Features

‎packages/solid/CHEATSHEET.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ import {
4040
untrack,
4141
flush,
4242
onSettled,
43+
onFlush,
4344
createContext,
4445
useContext,
4546
children,
@@ -140,7 +141,19 @@ onSettled(() => {
140141
});
141142
```
142143

143-
`onSettled` works in component bodies (after first reactive settle) **and** in event handlers (defer work until the triggered transition settles). For component-level setup-and-teardown, **use `onSettled` with a returned cleanup, not `onCleanup` directly** — `onCleanup` is reserved for reactive cleanup inside computations (see Advanced).
144+
`onSettled` works in component bodies (after first reactive settle) **and** in event handlers (defer work until the triggered transition settles).
145+
146+
```ts
147+
// Keep a write out of another update's hold: runs once right after the
148+
// pending flush, never waits on async. For event handlers and effect
149+
// callbacks (dev warns ON_FLUSH_IN_OWNED_SCOPE in a body or computation).
150+
const select = (id: string) => {
151+
onFlush(() => setOpen(false)); // closes now even if onSelect navigates
152+
props.onSelect?.(id);
153+
};
154+
```
155+
156+
For component-level setup-and-teardown, **use `onSettled` with a returned cleanup, not `onCleanup` directly** — `onCleanup` is reserved for reactive cleanup inside computations (see Advanced).
144157

145158
---
146159

@@ -573,6 +586,8 @@ return <li class={cls} />;
573586
import { renderToString, renderToStream, isServer, isDev } from "@solidjs/web";
574587
```
575588

589+
Hydration adopts each async read the server answered (value or error) and never asks again; a hydrated `<Errored>` keeps the server's fallback until an input changes or `reset()`. Adopted computes still run once to track reads, with the global `Promise` and `fetch` faked (never settle): don't cache promises or `import()`s created in a compute.
590+
576591
`Portal` throws on the server. `Reveal` `order="together"` and `collapsed` require streaming (`renderToStream` — awaiting it yields the fully settled HTML string).
577592

578593
---

‎packages/solid/skills/solid-2.0/SKILL.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,14 @@ Also:
6262
The memo's `equals` (default `===`) stops the re-run.
6363
- No writes inside a memo, effect compute, or component body (dev throws).
6464
Write from event handlers, `onSettled`, or actions.
65+
- Writes in one synchronous frame land together: if one starts async work
66+
(a navigation, a refetch), the rest are held with it. To land a write on
67+
its own (close a menu before calling `props.onSelect`), wrap it in
68+
`onFlush(() => setOpen(false))`. Not `queueMicrotask` or `setTimeout`.
69+
- Hydration adopts server answers without re-asking, but runs each adopted
70+
compute once to track reads with fake `Promise`/`fetch` that never settle.
71+
Never store a promise or `import()` created inside a compute in a cache
72+
that outlives it; cache resolved values, or start the load outside.
6573
- No reactive reads at the top of a component body; read in JSX, a memo, or
6674
`untrack`. Flow callbacks (`<For>`, `<Show>`, `<Match>`) are owners, not
6775
tracking scopes: read their accessor arguments in JSX, not at the top.

0 commit comments

Comments
 (0)