Skip to content

RFC 33: Warn when the server renders with two copies of @solidjs/web #34

Open

Description

@yumemi-thomas

One of a series of small proposals, in order; the tracking issue lists them. Depends on: none beyond upstream PR solidjs#69.

Summary

The server runtime looks at the first chunk of each stream it renders. If that chunk has HTML markup but no hydration keys, it prints one warning per process: nothing will hydrate, and the likely cause is that the compiled modules and @reactivescript/runtime use different copies of Solid (solid-js, and with it @solidjs/web).

Motivation

Compiled .rx modules import Solid's server templates from @solidjs/web. The runtime renders them with renderToStream, also from @solidjs/web. Hydration keys (the _hk attributes the client uses to find the server's nodes) come out only when both use the same copy.

Two copies happen easily in a server build. The common way: Solid is linked from a checkout (or otherwise not an installed package), so Vite bundles it into the server build, while the runtime, an installed package, stays external and imports its own copy. The prototype's runtime README (RFC 30's commit 2cab64b) documents the fix: name them in ssr.external, "otherwise the compiled templates and the runtime render with two @solidjs/webs, and nothing hydrates".

What the developer sees today: the server responds with a page that looks right. On the client nothing hydrates (no keys to match), and nothing says why. There is no error on either side.

Proposal

In the server build's app.stream(view, sink), the runtime wraps the sink. On the first chunk written:

  • if it contains an HTML tag (/<[a-z][^>]*>/i)
  • and no hydration key (/\b_hk=/)
  • and no warning has been printed yet in this process,

it calls console.warn once:

[reactivescript] the server's first chunk has markup but no hydration keys, so the client will not
hydrate it. One likely cause: the compiled modules and @reactivescript/runtime load different copies
of Solid (solid-js, and with it @solidjs/web): keep Solid, the runtime and libraries that render all
external to the server build, or all bundled together

The message states the symptom and names the copies as a likely cause, not a certain one: the check sees only the output.

The chunk is then written unchanged. Rendering is not affected and nothing is thrown. The check is skipped where the runtime renders in a server-component scope (the SV_SCOPE test mode), whose output has no keys by design.

The fix the message points to:

// vite.config: one copy each on the server
ssr: { external: ["solid-js", "@solidjs/web", "@solidjs/signals", "@solidjs/router", "@reactivescript/runtime"] }

Drawbacks and alternatives

  • It is a heuristic over output text. A first chunk that is all text (no tags) is not checked, and a page whose first chunk is markup that Solid would legitimately leave unkeyed would warn falsely. No such case has been seen in the examples or tests.
  • It only checks the first chunk of a stream, and warns once per process, so it costs one regex test per request.
  • Alternative: detect the duplicate directly (compare module identities of @solidjs/web seen by the compiled code and by the runtime). The compiled code does not hand the runtime its @solidjs/web, so this would need a new export or global, which is more machinery than the symptom check.
  • Alternative: document it only. The failure is silent, which is why this proposes a warning as well.

Prototype

Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript: commit 12b5dd3, runtime part only, and 99c5aad, which rewords the message after review. Code: stream in ref/compile/rt-server.ts, from which the server build of @reactivescript/runtime is built. The same commit's change to compiler/test/vite.mjs (finding a Solid Vite plugin that loads .rx) is harness work, not part of this proposal. No spec rule: this is a diagnostic of the runtime, not of the language. f031b0b names Solid in the message and adds the tests (runtime/test.mjs): with one copy nothing is printed; with the compiled module on its own solid-js and @solidjs/web the page has no keys and the warning is printed once for two requests; with a second @solidjs/web over the same solid-js the page is still keyed and nothing is printed. So the copy that matters is solid-js's (it holds the render's hydration context), which a bundler that inlines @solidjs/web normally inlines with it. The router-ssr case of compiler/test/vite.mjs (RFC 30) is the setup it guards: it keeps Solid, the router and the runtime in ssr.external.

Revised after the second review (2026-11-21, cdc00d4)

RFC 33, after the second review. The warning now says the client may not be able to hydrate the page, notes that intentional unkeyed markup or keys in a later chunk look the same, and names two copies of Solid as the cause to check first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions