---
description: Web platform runtime — rendering, SSR, Portal, Dynamic
globs: packages/web/**
alwaysApply: false
---

# Solid Web (`@solidjs/web`)

## Package Role

Web-specific runtime providing DOM rendering, hydration, SSR methods, DOM operations, and web-only components. Has conditional exports: browser gets `dist/web.js`, server environments get `dist/server.js`.

## Client Entry (`src/index.ts`)

Re-exports everything from `client.js`: `render`, `hydrate`, `insert`, `spread`, `template`, `delegateEvents`, `getNextElement`, `setProperty`, `setAttribute`, `className`, `style`, `addEvent`, `useHead`, `getRequestEvent`, `getHydrationWriter`, `takeHydrationValue`, `getTraceContext`, the cookie codec, the server-function registry (`isServerFunction`, `getServerFunctionMetadata`, `getServerFunctionRPC`), element claims (`registerElementClaim`, `claimElement`, `claimElementTree`), and the DOM constant sets (`SVGElements`, `MathMLElements`, `DelegatedEvents`, …). Also re-exports `server-mock.js` (see below) and `response.js` (`redirect`, `reload`, `respond`, `markSafeError`, …).

Additional exports:
- `Portal`, `Dynamic`, `dynamic`, `dynamicComponent`, `clientOnly`
- `httpStatus`, `httpHeader` (no-ops on the client)
- Flow controls re-exported from `solid-js`: `For`, `Show`, `Switch`, `Match`, `Errored`, `Loading`, `Repeat`, `Reveal`, `NoHydration`, `Hydration`
- `isServer: false`, `isDev: boolean` (`_SOLID_DEV_`)

## Server Entry (`src/index.server.ts`)

Re-exports everything from `server.js` and `response.js`:
- `renderToString`, `renderToStream` (there is no `renderToStringAsync` — `renderToString` awaits async)
- SSR helpers: `ssr`, `ssrElement`, `ssrElementAttribute`, `ssrAttribute`, `ssrClassName`, `ssrStyle`, `ssrStyleProperty`, `ssrStyleProperties`, `ssrGroup`, `ssrHydrationKey`, `ssrClaim`, `ssrLinkClaim`, `ssrSelectValues`, `resolveSSRNode`, `escape`
- Request/response: `getRequestEvent`, `createRequestEvent`, `createResponseStub`, `createSSRResponse`, `commitEventResponse`, `composeMiddleware`, `configureServerErrors`, `reportRequestFailure`, plus `redirect`, `reload`, `respond` and the cookie codec
- Hydration: `HydrationScript`, `generateHydrationScript`, `getHydrationWriter`, `takeHydrationValue`, `useHead`
- The client-only DOM APIs (`render`, `hydrate`, `insert`, `spread`, `template`, `delegateEvents`, …) are exported as a `notSup` stub that throws when called on the server

Additional:
- Simplified `Dynamic`/`dynamic` (no memoization — server is stateless), `dynamicComponent`
- `Portal` throws error (not supported server-side)
- `clientOnly` (server half: renders the fallback, emits preload hints)
- `httpStatus`, `httpHeader` (declare status/headers on the current request event)
- Same flow-control re-exports from `solid-js` as the client entry
- `isServer: true`, `isDev: boolean` (`_SOLID_DEV_`; the server has a dev build too, `dist/server.dev.js`)
- Request-event scoping (`provideRequestEvent`, `AsyncLocalStorage`-backed) lives in `@solidjs/web/storage`, not in this entry

## Portal Component

Renders children to a different DOM location (defaults to `document.body`).

- Uses text markers (`treeMarker`, `startMarker`, `endMarker`) for tracking
- Creates element proxy to track `_$host` property
- SVG-aware
- Cleanup removes all nodes between markers

## Dynamic Component

Renders components or elements dynamically based on `component` prop.

- `createMemo` caches the component reference
- Handles: function components, string tags (HTML/SVG via `SVGElements` set), undefined
- Hydration-aware via `sharedConfig.hydrating` and `getNextElement()`
- Uses `spread()` to apply props to native elements

## Submodules (each with its own export path and source directory)

- **`server-functions/`** (`./server-functions`, `/server`, `/client`, `/rich-args`) — the server-function runtime: request-event scoping (`provideEvent`), invocation wrapping, argument/result (de)serialization over seroval, failure sanitization on the result walk, request body caps, and the encrypted flash-cookie mechanism for no-JS form flows (AES-GCM, key derived via HKDF from the bundler-injected `globalThis.__SOLID_SECRET__`, domain-separated). The conformance matrix and pinned rulings live in `test/server/server-function-matrix/MATRIX.md` — consult it before changing semantics; add rulings there when making them.
- **`frames/`** (`./frames`, `/server`, `/client`) — frames transport: eager client consumer + transport with a lazily-loaded codec.
- **`serialization/`** (`./serialization`, `./serialization/decode`) — the seroval-based streaming codec shared by server functions and frames; the decoder owns promise lifecycle (every deferred it creates must be owned/defused — see the #3235/#3267 rulings in the matrix).
- **`storage/`** (`./storage`) — persisted storage helpers over `seroval`/`seroval-plugins`.

## Server-Mock (`src/server-mock.ts`)

Browser-safe stubs that log errors if server APIs are accidentally used in browser: `renderToString`, `renderToStringAsync`, `renderToStream`, SSR helpers.

## Build Outputs

- `dist/web.js` — production browser
- `dist/web.observe.js` — observe-tier browser (`observe` export condition; `_SOLID_OBSERVE_` on, `_SOLID_DEV_` off — interaction provenance wiring kept, checks folded)
- `dist/web.dev.js` — development browser (both flags on)
- `dist/server.js` — production server (Node/Deno/Worker)
- `dist/server.dev.js` — development server (`development` export condition, nested under `node`/`worker`/`deno`)

Every dev artifact is `<entry>.dev.js` beside its prod `<entry>.js` — the same rule for `frames/`, `server-functions/`, and the other packages. All artifacts are ESM only (no `.cjs` twins, no `require` export branch, no `types-cjs/`): the published `engines.node >= 22.12` floor `require()`s ESM natively, so a CJS host resolves the same files through the same conditions. Nothing shipped may contain a top-level `await` (`require(esm)` throws on it; the signals dist test scans for it). Observe artifacts are `<entry>.observe.js` and exist only for entries that contain wiring (here: the browser entry); entries without wiring fall through to prod under `observe`. Tier-ness is a build mode, not an entry. Gate a site on `"_SOLID_OBSERVE_"` when production observability needs it (labels, attribution hooks), on `"_SOLID_DEV_"` when only a developer at a console does. See `documentation/plans/observe-tier-plan.md`.

Rollup with Babel for JSX transformation, `@rollup/plugin-replace` for dev/prod flags.
