Skip to content

serverFunctions.components: no way for a host integration to declare it owns the document wiring (spurious warning) #340

Description

@ryansolid

Problem

When serverFunctions: { components: true } is set without SSR start mode, configResolved warns unconditionally (src/index.ts, the serverComponents && !(options.start && options.ssr) branch):

serverFunctions.components is set without SSR start mode … The document wiring — render plugin, bootstrap script, and the client-side installServerComponents() call — is emitted by SSR start mode's generated entries; without it, server components only mount from post-boot streams and your client code must call installServerComponents() itself.

That's the right warning for an app author with authored entries. But meta-framework hosts that compose the plugin (ssr: true, no start) and emit all of the document wiring themselves hit it too, on every dev start and build, with no way to acknowledge it:

  • The new Astro adapter (@astrojs/solid-js v8) installs ServerComponentPlugin + frameTransformDirectResult around its island renders, injects installServerComponents() through Astro's before-hydration stage, and dispatches the endpoint through virtual:solid-server-function-handler from an injected route. t=0 document adoption works end to end (zero endpoint requests at boot, morphs preserve slot DOM identity) — and the warning still prints.
  • TanStack Start's Solid integration is in the same position: host-owned entries and dispatch, same spurious warning.

So the warning currently reads as "this is misconfigured" for exactly the integrations that configured it correctly.

Proposal

Give hosts an explicit way to declare they own the document wiring, and skip the warning on that path. Options, roughly in order of preference:

  1. A dedicated acknowledgement on the option, e.g. serverFunctions: { components: true, documentWiring: 'host' } (or components: 'external'). Self-documenting, and the plugin could later key other host-mode behavior off it.
  2. Treat existing host signals as the acknowledgement — serverFunctions.devMiddleware: false and/or start.external: true already say "a host owns dispatch/serving"; either could reasonably imply the host owns the client wiring too.
  3. At minimum, demote/reword so composing hosts don't ship a scary log to their users on every build.

Also: the message is stale

The text still lists "the bootstrap script" as a required piece, but the head bootstrap injection was removed — serialized server-component references self-bootstrap the registry (the _$SC idempotent expression rides each hydration script's first reference). The remaining app-side pieces are just the render plugin (+ direct-call transform) and installServerComponents(). Worth fixing in the same pass regardless of which option lands.

Seen on @solidjs/vite-plugin@3.0.0-next.37 with solid-js / @solidjs/web 2.0.0-rc.5.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions