architecture · git:20261116.831792d · 2026-11-16 · sha256 72b512146324d97d
architecture git:20261116.831792dA
Immutable. This exact content never changes and is served at /api/v1/blob/72b512146324d97d.
---
description: Core architecture and mental model for the SolidJS monorepo
alwaysApply: true
---
# Architecture
SolidJS core monorepo — a declarative JavaScript UI library that compiles templates to real DOM nodes with fine-grained reactivity. Version 2.0.
## Monorepo Structure
PNPM workspaces + Turborepo. All packages version together as one changesets fixed group.
- **`@solidjs/signals`** (`packages/signals/`): The reactive engine — signals, memos, effects, async, stores, optimistic lanes, scheduler. Internal to this repo; everything else builds on it (see `signals.mdc`).
- **`solid-js`** (`packages/solid/`): Core runtime — component model, flow controls, context, hydration. Wraps `@solidjs/signals` with a UI layer.
- **`@solidjs/web`** (`packages/web/`): Web platform runtime — `render`, `hydrate`, SSR methods, `Portal`, `Dynamic`, and the DOM operation runtime. Also hosts the server-function runtime (`server-functions/`), the frames transport (`frames/`), the seroval streaming codec (`serialization/`), and storage helpers (`storage/`), each behind its own export path.
- **`@solidjs/h`** (`packages/h/`): Hyperscript/JSX factory — less-optimal JSX alternative.
- **`@solidjs/element`** (`packages/element/`): Web Components wrapper.
- **`@solidjs/html`** (`packages/html/`): Build-less tagged template literals.
- **`@solidjs/universal`** (`packages/universal/`): Universal runtime for custom renderers.
- **`@solidjs/babel-plugin`** (`packages/babel-plugin/`): Babel plugin for JSX compilation.
- **`@solidjs/compiler`** (`packages/compiler/`): Native (Oxc) JSX compiler.
- **`test-integration`** (`packages/test-integration/`): Integration tests against external repos.
## Dependency Chain
```
@solidjs/signals (reactive primitives)
↓
solid-js (component model, flow controls, context, hydration)
↓
@solidjs/web (DOM rendering, SSR, Portal, Dynamic, DOM ops)
@solidjs/universal / @solidjs/h / @solidjs/html
```
`solid-js` re-exports all reactivity primitives from `@solidjs/signals` and adds the component/JSX layer on top. `@solidjs/web` provides the platform-specific runtime, including the DOM operation runtime. Compilers live in `@solidjs/compiler` (native) and `@solidjs/babel-plugin`; their validators and codegen must stay in parity (shared test expectations).
## Component Model
Components are plain functions: `(props: P) => JSX.Element`. No classes, no hooks. Component creation is wrapped in `untrack()` to avoid reactive tracking during initialization.
Component types enforce children constraints:
- `Component<P>` — no implicit children
- `VoidComponent<P>` — forbids children
- `ParentComponent<P>` — optional `JSX.Element` children
- `FlowComponent<P, C>` — requires children of type `C`
## Reactivity Integration
All reactivity comes from `@solidjs/signals`:
- `createSignal()` → `[getter, setter]`
- `createMemo()` → derived computation
- `createEffect(compute, effect)` — separate compute and effect phases
- `createStore()` → proxy-based deep reactivity
- `flush()` — updates are batched; must flush to process
## Flow Controls
Built on signals primitives: `For` (mapArray), `Repeat` (repeat), `Show` (createMemo), `Switch/Match` (children + memos), `Errored` (createErrorBoundary), `Loading` (createLoadingBoundary), `Reveal` (createRevealOrder).
All support `keyed` mode (identity comparison) vs non-keyed (truthiness). Function children in `Show`/`Match` receive narrowed accessors with stale-read protection.
## Build-time Constants
`_SOLID_DEV_` is replaced at build time (see rollup configs). Use it for dev-only code to enable tree-shaking in production.
## Commands
- `pnpm install` — install dependencies (pnpm 9.15+ required)
- `pnpm build` — Turborepo build (all packages)
- `pnpm types` — generate TypeScript declarations
- `pnpm test` — run all tests + type tests
- `pnpm coverage` — coverage reports
- `pnpm format` — Prettier formatting (also runs on pre-commit)
## Key External Dependencies
- `seroval` / `seroval-plugins` — serialization for SSR, server functions, and storage