Skip to content

Commit 6f4fa94

Browse files
ryansolidclaude
andauthored
docs: sync diagnostics pages and the Vite plugin's test environment (#1665)
* docs: sync diagnostics pages and the Vite plugin's test environment - Regenerate the diagnostics reference from solid next 6cca8b57: adds STORE_WRITE_OUTSIDE_SETTER (#4194) and UNCOMMITTED_INPUT_OVERWRITTEN (#4205), drops BINDING_SLOT_POSITION (binding slots were removed), and picks up skill edits to EFFECT_RELAY_TEAR, LOWERCASE_EVENT_ATTRIBUTE, REACTIVITY_HALTED, SSR_BOUNDARY_WATERFALL and SSR_LIVE_HOLE_LATCHED. The generator's FIX_STARTS entry for SSR_BOUNDARY_WATERFALL follows the skill's new capitalization, and the dead BINDING_SLOT_POSITION entry goes. - The Vite plugin no longer defaults test.environment to jsdom (vite-plugin-solid #459): the testing guide drops the "browser mode still needs jsdom" note and troubleshooting entry, browser mode no longer installs jsdom, and a new entry covers `document is not defined`. The plugin options reference and the Solid 1 migration guide say to set the environment. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R9d4iekBWmtH343gNAGJpd * docs: regenerate diagnostics against solid-js@2.0.0-rc.17 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R9d4iekBWmtH343gNAGJpd --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 14c454c commit 6f4fa94

14 files changed

Lines changed: 141 additions & 85 deletions

‎scripts/extract-diagnostics.mjs‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,6 @@ const STANDALONE_REWRITES = [
7070
// error, so the map tracks the skill.
7171
const FIX_STARTS = {
7272
ACTION_CALLED_IN_OWNED_SCOPE: "Actions are imperative entry points",
73-
BINDING_SLOT_POSITION: "The rule: a slot property is a JSX attribute value",
7473
CLEANUP_IN_FORBIDDEN_SCOPE: "return a cleanup function from the callback",
7574
EFFECT_WRITES_OWN_SOURCE:
7675
"The written value is a function of what the effect reads",
@@ -79,7 +78,7 @@ const FIX_STARTS = {
7978
LAZY_ASSET_UNMAPPED: "This is bundler-plugin configuration",
8079
PENDING_ASYNC_UNTRACKED_READ: "Async values must be read where tracking",
8180
RUN_WITH_DISPOSED_OWNER: "This usually means a stale owner",
82-
SSR_BOUNDARY_WATERFALL: "the same repairs apply, in the same order",
81+
SSR_BOUNDARY_WATERFALL: "The same repairs apply, in the same order",
8382
SSR_RENDER_ERROR_CONTAINED: "In every case the repair is",
8483
SSR_STREAM_ABANDONED: "At volume it is the cost",
8584
UNRECOGNIZED_INSERT_VALUE: "Usually a component function inserted",

‎src/routes/(5)guides/(14)testing.mdx‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -146,15 +146,10 @@ The configuration above sets `globals: false`, so the explicit `afterEach(cleanu
146146
Choose browser mode when jsdom cannot provide the behavior that the test needs.
147147
The maintained browser-mode template uses the Playwright provider with headless Chromium.
148148

149-
:::note[Browser mode still needs jsdom installed]
150-
When `test.environment` is unset, `@solidjs/vite-plugin` supplies a jsdom environment and Vitest resolves that dependency before it starts the browser pool.
151-
Without jsdom, the Chromium test can pass while the Vitest command exits with a missing-dependency error.
152-
:::
153-
154149
For a new test setup, install the complete dependency set:
155150

156151
```sh
157-
pnpm add -D vitest jsdom @solidjs/testing-library @testing-library/jest-dom @vitest/browser-playwright playwright
152+
pnpm add -D vitest @solidjs/testing-library @testing-library/jest-dom @vitest/browser-playwright playwright
158153
pnpm exec playwright install chromium
159154
```
160155

@@ -380,11 +375,11 @@ The write is staged and the batch has not landed when the next line runs.
380375
Call `flush()` after the event and before the assertion.
381376
For an async source, `flush()` does not help; await `resolve(() => value())` or use an asynchronous query.
382377

383-
### The Chromium test passes but Vitest exits with a missing-dependency error
378+
### A component test fails with `document is not defined`
384379

385-
jsdom is not installed.
386-
`@solidjs/vite-plugin` supplies a jsdom environment when `test.environment` is unset, and Vitest resolves that dependency before starting the browser pool.
387-
Keep `jsdom` in the development dependencies alongside the browser provider.
380+
The `test` block does not set `environment`, so Vitest runs the file in Node.
381+
`@solidjs/vite-plugin` does not choose a test environment.
382+
Set `environment: "jsdom"` (or `"happy-dom"`) for component tests, or enable browser mode.
388383

389384
### A server test runs under jsdom
390385

‎src/routes/(6)migration/(0)from-solid-1.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,8 @@ Treat those imports as host-integration work and confirm them against the owning
397397
## Update tests
398398

399399
Update test compilation to use the renderer's JSX runtime.
400+
The Vite plugin no longer sets `test.environment`.
401+
Set `environment: "jsdom"` (or `"happy-dom"`) in the Vitest configuration for component tests; without it, Vitest runs them in Node.
400402
For web component tests, resolve the browser and development package conditions so tests exercise `@solidjs/web` rather than the server entry.
401403
Keep Testing Library cleanup or call render disposers explicitly.
402404

‎src/routes/reference/(1)solid-js/(8)diagnostics/(0)index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,6 @@ Naming your memos and effects (`{ name }`) turns the trailing `effect` in the `i
5454
| [`ASYNC_OUTSIDE_LOADING_BOUNDARY`](/reference/solid-js/diagnostics/async-outside-loading-boundary) | `async` | `warn` | Async computation outside Loading boundary (non-halting; root mount is deferred) |
5555
| [`ASYNC_STORE_SETTER`](/reference/solid-js/diagnostics/async-store-setter) | `write` | `error` | Store setter callback returned a Promise (setters are synchronous transactions) |
5656
| [`ASYNC_WATERFALL`](/reference/solid-js/diagnostics/async-waterfall) | `perf` | `info`, `warn` | 2+/3+ sequential async flights, origin-proven (attribution enabled) |
57-
| [`BINDING_SLOT_POSITION`](/reference/solid-js/diagnostics/binding-slot-position) | `ssr`, `render` | `warn`, `error` | Binding-slot value where it cannot bind; `data.reason` names the position (spread is an error and throws), client reasons `orphan`/`fill-shape` |
5857
| [`CLEANUP_IN_FORBIDDEN_SCOPE`](/reference/solid-js/diagnostics/cleanup-in-forbidden-scope) | `lifecycle` | `error` | `onCleanup` inside trackedEffect/onSettled |
5958
| [`DYNAMIC_ASYNC_COMPONENT`](/reference/solid-js/diagnostics/dynamic-async-component) | `ssr` | `error` | An async `dynamic()` source landed on a client component function, which cannot serialize for adoption; the memo rejects (observe + dev; rejects in every tier) |
6059
| [`EFFECT_RELAY_TEAR`](/reference/solid-js/diagnostics/effect-relay-tear) | `perf` | `info`, `warn` | Reader ran twice for one root change because an effect relayed it; `warn` when derivable or repeated (attribution enabled) |
@@ -105,8 +104,10 @@ Naming your memos and effects (`{ name }`) turns the trailing `effect` in the `i
105104
| [`SSR_SUBTREE_ABANDONED`](/reference/solid-js/diagnostics/ssr-subtree-abandoned) | `ssr` | `warn` | A failed fragment's pending descendants were discarded (observe + dev) |
106105
| [`SSR_UNDECLARED_LIVE_SOURCE`](/reference/solid-js/diagnostics/ssr-undeclared-live-source) | `ssr` | `warn` | A document render is still pumping an async iterable in server-component scope 5s in — declare the function `live(...)` or bound the source (dev) |
107106
| [`STACKED_HOLDS`](/reference/solid-js/diagnostics/stacked-holds) | `responsiveness` | `warn` | 3+ interactions were waiting in one hold when it committed — repeats piled behind the same source (attribution enabled) |
107+
| [`STORE_WRITE_OUTSIDE_SETTER`](/reference/solid-js/diagnostics/store-write-outside-setter) | `write` | `warn` | Store proxy written, deleted from, or defined on outside its setter; the write is ignored (once per store object and key) |
108108
| [`STRICT_READ_UNTRACKED`](/reference/solid-js/diagnostics/strict-read-untracked) | `strict-read` | `warn` | Untracked reactive read in component/effect body |
109109
| [`SYNC_NODE_RECEIVED_ASYNC`](/reference/solid-js/diagnostics/sync-node-received-async) | `lifecycle` | `error` | `sync: true` computation returned a Promise / AsyncIterable |
110+
| [`UNCOMMITTED_INPUT_OVERWRITTEN`](/reference/solid-js/diagnostics/uncommitted-input-overwritten) | `render` | `warn` | A stateful property binding (`value`/`checked`/…) re-wrote an unchanged value over an edit the user never committed to the signal (dev; client) |
110111
| [`UNRECOGNIZED_INSERT_VALUE`](/reference/solid-js/diagnostics/unrecognized-insert-value) | `render` | `warn` | Value at an insert position the renderer cannot render; skipped (dev; server and client) |
111112
| [`UNSCOPED_HOLE_ALLOCATED_IDS`](/reference/solid-js/diagnostics/unscoped-hole-allocated-ids) | `render` | `warn` | Unscoped hole was handed a function whose content took ids at a position the other side does not share; keys permute (dev) |
112113
| [`UNSTABLE_LIST_IDENTITY`](/reference/solid-js/diagnostics/unstable-list-identity) | `perf` | `warn` | `mapArray`/`For` recreated rows for equivalent items (attribution enabled) |

‎src/routes/reference/(1)solid-js/(8)diagnostics/binding-slot-position.mdx‎

Lines changed: 0 additions & 62 deletions
This file was deleted.

‎src/routes/reference/(1)solid-js/(8)diagnostics/effect-relay-tear.mdx‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,18 +35,23 @@ Derived state kept in sync by an effect: `createEffect(() => f(a()), v => setS(v
3535
The message names a reader that ran twice for ONE write of `a` — once in the flush where `a` changed (against the stale `S`), once after the effect's write landed — so its first frame was inconsistent.
3636
That double run is proven from the cause chain; the rest of the message is confidence:
3737

38+
- "The written value is the effect's compute output" — by Solid's contract the compute half is a pure function of its tracked reads, so the value is derivable. Repair: `const s = createMemo(() => f(a()))`, delete the effect and the signal. This form warns on its own once it has repeated (`data.copy: true`), even with no double-running reader — everything reading the copy paints a flush behind everything reading the source.
39+
- "The written value is `a` itself" (`data.passthrough`) — the prop-to-state port. Repair: read `a` where `S` was read; a memo only if a stable derivation is genuinely needed.
40+
- "Nothing else writes `S`" (`data.soleWriter`, `copy` false) — derived state if the value is computed from what the effect reads: same memo repair. If the effect measures (layout, `Date.now()`, a ref), the tear is the cost of measuring.
41+
- "`S` has other writers — editable state reset from a source" (`copy` true, `soleWriter` false; `info` until it repeats) — the controlled-input shape. If resetting local editable state when the source changes is the intent, the tear is its cost; if `S` only ever mirrors the source, drop the copy.
42+
- Neither — the written value is not the compute output and the signal has other writers. If the effect reads something outside the graph, the tear is the cost of measuring and the finding is a fact to accept; if the value is computed from what the effect reads, it is still a memo.
43+
44+
An effect whose apply half takes no argument (`createEffect(open, () => setFlipped(measure()))`) is reading something other than its compute output, so a matching write is never taken as a copy and its tears stay `info` however often they repeat: the cost of measuring.
45+
One that takes the value (`v => setS(v)`, `v => setLabel(v ? "Close" : "Open")`) is judged as above and warns once it has repeated, a measurement included (`i => setLeft(offsets[i])` with stable layout): drop the parameter if the write does not use it.
46+
3847
:::note[Performance pathologies (from the attribution engine)]
3948
These fire only while attribution is enabled and describe cost, not incorrect behavior.
4049
The numbers in the message are measurements, not guesses.
4150
:::
4251

4352
## How to fix it
4453

45-
- "The written value is the effect's compute output" — by Solid's contract the compute half is a pure function of its tracked reads, so the value is derivable. Repair: `const s = createMemo(() => f(a()))`, delete the effect and the signal. This form warns on its own once it has repeated (`data.copy: true`), even with no double-running reader — everything reading the copy paints a flush behind everything reading the source.
46-
- "The written value is `a` itself" (`data.passthrough`) — the prop-to-state port. Repair: read `a` where `S` was read; a memo only if a stable derivation is genuinely needed.
47-
- "Nothing else writes `S`" (`data.soleWriter`) — derived state without the identity proof; same memo repair.
48-
- "`S` has other writers — editable state reset from a source" (`copy` true, `soleWriter` false; `info` until it repeats) — the controlled-input shape. If resetting local editable state when the source changes is the intent, the tear is its cost; if `S` only ever mirrors the source, drop the copy.
49-
- Neither (`info` until it repeats) — the written value is not the compute output and the signal has other writers. If the effect reads something outside the graph (layout, `Date.now()`, a ref), the tear is the cost of measuring and the finding is a fact to accept; if the value is computed from what the effect reads, it is still a memo.
54+
Do not defer the write to a microtask to quiet it; that only hides the cause chain.
5055

5156
## In tests
5257

‎src/routes/reference/(1)solid-js/(8)diagnostics/lowercase-event-attribute.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ In a captured artifact the same finding is an event with `code: "LOWERCASE_EVENT
3030

3131
## Why it fires
3232

33-
A function was set on an attribute whose name starts with `on` but is not an event handler (`data.name`): a lowercase `onclick`, or a leftover 1.x `on:click`.
33+
A function was set on an attribute whose name starts with `on` but is not an event handler (`data.name`): a lowercase `onclick`, or a leftover 1.x `on:click` passed through a spread (on a native element it is a compile error).
3434
In 2.0 only `on` + an uppercase letter binds an event; anything else is a plain attribute, so the function was stringified into it and never runs.
3535
Once per attribute name.
3636

‎src/routes/reference/(1)solid-js/(8)diagnostics/reactivity-halted.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ An earlier uncaught error halted the reactive system; subsequent updates are ign
3535
## How to fix it
3636

3737
Do not treat this code as the bug — find the original error above it (or add an error boundary with `<Errored>`) and fix that.
38+
The `in <App> › …` line under the message (repeated on the "Update ignored" notice) is the owner path of the computation the error escaped from: start there.
3839

3940
## In tests
4041

‎src/routes/reference/(1)solid-js/(8)diagnostics/settled-cleanup-unowned.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ In a captured artifact the same finding is an event with `code: "SETTLED_CLEANUP
3131
## Why it fires
3232

3333
`onSettled` returned a cleanup while running in an unowned scope, so the cleanup cannot be honored.
34+
Throws in dev; in production the cleanup is dropped.
3435

3536
## How to fix it
3637

0 commit comments

Comments
 (0)