solid-core · git:20260904.1edb1e3 · 2026-09-04 · sha256 6157c0c098a60fd4

solid-core git:20260904.1edb1e3A

Immutable. This exact content never changes and is served at /api/v1/blob/6157c0c098a60fd4.

---
description: Solid core runtime — component model, flow controls, context, and hydration
globs: packages/solid/**
alwaysApply: false
---

# Solid Core (`solid-js`)

## Package Role

Wraps `@solidjs/signals` with a UI component layer. Re-exports reactivity primitives and adds: components, context, flow controls, hydration, and JSX types.

## Dual Runtime

Two parallel runtimes selected by conditional exports — keep them in sync when touching either:

- **`src/client/`** — browser runtime. `src/index.ts` re-exports signals primitives from `@solidjs/signals`, component utilities (`export *` from `client/component.js` and `client/flow.js`), context/children from `client/core.js`, hydration facades from `client/hydration.js`, plus no-op SSR stubs (`ssrHandleError`, `ssrScope`, `runInServerComponentScope`) and the dev-only `DEV` object.
- **`src/server/`** — full server mirror (`component.ts`, `core.ts`, `flow.ts`, `hydration.ts`, `signals.ts`, `shared.ts`): mock signals facades and server implementations of the same surface. NOT empty — server-side store/signal typing changes must be applied here too (e.g. `server/signals.ts` carries the store facade types).

## Component Creation

`createComponent(Comp, props)` wraps execution in `untrack()` — components never track during creation. Dev mode wraps with `devComponent()` attaching `_props`, `_name`, `_component` to the owner.

`lazy(fn, options?, moduleUrl?)` — supports `{ export }` for named exports; returns the component augmented with `.preload()` and `moduleUrl`. Loading rides async-memo semantics (NotReady suspension), not a sentinel return.

`createUniqueId()` is hydration-aware via `sharedConfig.getNextContextId()`.

## Context System

`createContext(defaultValue)` creates a context with a Symbol ID. Storage uses `setContext`/`getContext` from `@solidjs/signals` (owner-based, not global). `children(fn)` resolves via `createMemo` + `flatten()`, returns accessor with `.toArray()`.

## Flow Controls (`client/flow.ts`)

| Component | Backing Primitive | Key Behavior |
|-----------|------------------|--------------|
| `For<T>` | `mapArray()` | List rendering, supports `keyed` (boolean or key fn) |
| `Repeat` | `repeat()` | Count-based rendering with `from` offset |
| `Show<T>` | `createMemo` | Conditional, function children get narrowed accessor |
| `Switch/Match` | `children()` + memos | Sequential evaluation, short-circuit |
| `Errored` | `createErrorBoundary()` | Fallback: element or `(err, reset) => JSX.Element` |
| `Loading` | `createLoadingBoundary()` | Async fallback boundary |
| `Reveal` | `createRevealOrder()` | Reveal-order coordination |

Function children in `Show`/`Match` have stale-read protection — accessing after unmount throws via `narrowedError()`.

## Hydration (`client/hydration.ts`)

`sharedConfig` coordinates hydration state (`hydrating`, resource registry, `getNextContextId()`); `enableHydration()` arms it. The module also exports hydration-aware facades that shadow signals primitives during hydration (`createMemo`, `createSignal`, `createErrorBoundary`, `createOptimistic`, store creators) — type changes to store/signal APIs must be mirrored in these facades.

## Naming Conventions

- Component types: PascalCase (`Component`, `FlowComponent`, `ParentComponent`)
- Functions: camelCase (`createComponent`, `createContext`, `useContext`)
- Dev-only internal props: `_props`, `_name`, `_component`; `$DEVCOMP` symbol marks components