preactjs/preact
github.com/preactjs/preact ↗ · 302 files · 1.5 MB
Fast 4kB alternative to React with the same modern API.
Overview
Preact is a component-based UI library for developers building browser interfaces with JSX, functions, classes, hooks, and context. At commit 45728eb4315bcb22c5d50b8fec0bbac419eaa799, its renderer reconciles virtual nodes against live DOM, supports hydration and portals, and exposes renderer callbacks that power separately bundled addons. React compatibility, development diagnostics, JSX compiler helpers, and testing utilities surround the core; server rendering delegates to the separate preact-render-to-string package.
System map
The repository packages a DOM renderer and several addons under one public npm package. Core rendering owns VNode trees, component instances, and DOM mutations; hooks and compatibility extend it through shared options callbacks. Server rendering crosses into an optional external package, while the demo is a separate Vite application inside the workspace. Rollup, Babel, and Terser produce the distributable modules, and GitHub Actions define validation and staged release workflows.
- src/index.js exports render, hydrate, createElement/h, Fragment, refs, cloning, Component, context, portals, child flattening, and options as the core API.
- The root package is preact 11.0.0; its export map publishes core, compat, debug, devtools, hooks, test-utils, JSX runtimes, and compatibility client/server/scheduler adapters.
- compat and debug manifests are private source/build metadata with separate dist modules; CONTRIBUTING describes addon manifests as publishing metadata rather than workspace projects.
- The pnpm workspace adds only demo; package.json selects pnpm 11.3.0 and Node 22.22.2, and workspace configuration enforces that Node engine.
- render stores the previous root on parentDom._children, while Component owns state and _nextState; these inspected core paths retain runtime state in objects associated with the DOM tree.
- scripts/build.mjs enumerates seven bundles and uses Rollup, Babel property renaming, a custom rest transform, and Terser; addons externalize preact imports.
- Server compatibility exports string, pipeable-stream, and readable-stream rendering from preact-render-to-string; the root declares it an optional peer.
- The demo uses Vite with automatic JSX and source aliases for core, hooks, devtools, JSX runtimes, React, and ReactDOM.
- Repository scripts define build, addon-specific watch modes, lint, formatting, minified Vitest tests, and separate core/compat TypeScript checks.
- Release automation responds to 11.* tags, consumes the tested npm-package artifact, creates a draft GitHub release, and stages npm publication with provenance; CONTRIBUTING describes a subsequent npm review and 2FA step.
Feature catalog
The primary user-facing surface is a library API for constructing and updating interfaces. Core provides components, DOM rendering, hydration, context, fragments, refs, and portals; addons provide hooks, React adapters, diagnostics, and test controls. Compiler-facing exports support both automatic JSX and precompiled HTML templates. The demo exposes a route-based playground for rendering scenarios and ecosystem integrations; it is documented as a debugging application.
- createElement and cloneElement normalize props and variadic children, extract keys, and extract refs for non-function element types; Fragment returns its children.
- Class components support setState, forceUpdate, derived state, mount/update callbacks, shouldComponentUpdate, and snapshot-before-update behavior.
- Hydration reuses matching existing DOM nodes, attaches function-valued props, reports missing-node mismatches through an option hook, and specially synchronizes textarea values.
- createContext provides Provider and Consumer interfaces, default values, and subscriptions that force consumer updates when the provider value changes.
- createPortal continues a VNode subtree in another DOM container; compat adds containerInfo to the returned node.
- preact/hooks implements useState/useReducer, passive and layout effects, refs, imperative handles, memoization, callbacks, context, debug values, error boundaries, and stable per-root IDs.
- React compatibility includes Children utilities, PureComponent, memo with a custom comparator, forwardRef, DOM lookup, unmounting, flushSync, and StrictMode as a Fragment alias.
- Compat supplies Suspense and lazy, use for promises or context, and useSyncExternalStore with separate server/hydration snapshots.
- Compat client adapters expose createRoot with render/unmount and hydrateRoot; server adapters expose string/static-markup and stream interfaces.
- The JSX runtime exports jsx, jsxs, jsxDEV, Fragment, jsxTemplate, jsxAttr, and jsxEscape; template helpers serialize attributes and escape dynamic children.
- Debug validates render containers, element types, refs, event-handler values, hook placement, excessive rerenders, and duplicate keys; devtools exposes an attachment bridge and custom hook names.
- The demo route table exposes Home, state-order, reorder, spiral, pythagoras, todo, fragments, profiler, key_bug, context, devtools, suspense, empty-fragment, people profiles, styled-components, Redux, MobX, textfields, reduxBug, suspense-router, nested-suspense, contenteditable, Zustand, and Redux Toolkit.
Data flow
Applications supply component types, props, children, and a DOM container; factories turn these into renderer-owned VNodes. Reconciliation links new nodes to previous nodes, updates component state, and applies DOM changes before committing refs and callbacks. Hook state belongs to component instances, with separate queues for pending values and effects. External stores, promises, and demo network responses enter through explicit adapters; the inspected core state path does not itself implement durable application persistence.
- createElement converts a type/props/children call into createVNode; the factory initializes tree pointers, component ownership, identity, flags, and an undefined constructor marker before invoking options.vnode.
- Automatic JSX uses a separate VNode factory with the same internal fields, negative identity counters, optional source metadata, and the shared options.vnode callback.
- render wraps application output in a Fragment root, passes previous VNodes or existing childNodes into diff, and collects ref and component callback queues for commitRoot.
- constructNewChildrenArray drops null/boolean/function children, converts primitives to text VNodes, wraps arrays in Fragments, clones reused VNodes, and assigns parent/depth/matching-index metadata.
- Child matching compares key and type; actual reorders trigger a longest-increasing-subsequence pass that marks matched nodes outside the subsequence for DOM insertion.
- diff creates class instances or BaseComponent-backed function instances, resolves context providers, assigns props/state, executes render, and recursively diffs the returned children.
- setState accumulates partial or functional updates in _nextState and schedules mounted components; the render queue deduplicates dirty components and sorts them by VNode depth.
- Hook calls index component.__hooks._list; reducer dispatch stores _nextValue after an Object.is comparison, and the before-render callback promotes pending values.
- DOM output uses ownerDocument for node creation, setProperty for property/attribute/event updates, and insert with moveBefore or insertBefore for placement.
- commitRoot applies refs before options._commit and component callbacks; hooks intercept the commit for layout effects and use after-paint queues for passive effects and deferred unmount cleanup.
- useSyncExternalStore reads a server snapshot during SSR or tracked hydration, caches the latest snapshot/getter, and subscribes to changes that force an update when Object.is detects a different value.
- People Browser fetches Random User JSON, maps login.username to the model identifier, replaces the users array, and renders observer-driven sorted links and profiles; local deletion mutates the model.
Behavior traces
The inspected flows cover initial rendering, a concrete Todo interaction, hydration, promise suspension and retry, portal rendering, and demo network loading. Each trace follows named functions across their input, state owner, and output boundary. Preact has library initialization and mounting rather than a server startup lifecycle. State retention in these flows is primarily the VNode/component graph, while the demo reads localStorage only for diagnostic switches.
- Initial mount: createElement → createVNode → render creates the Fragment root → diff selects component or element handling → diffChildren recursively reconciles output → commitRoot attaches refs and invokes callbacks.
- Demo startup: index.html loads index.jsx → its URL check conditionally calls initDevTools/initDebug → installLogger reads localStorage/URL switches → render mounts App into document.body.
- Todo typing: setProperty registers the input listener → eventProxy invokes setText → setText calls setState with target.value → enqueueRender schedules process → renderComponent diffs the component and commits the controlled input.
- Todo addition/removal: addTodo concatenates a counter-keyed item and clears text, or removeTodo filters by data-id → setState → enqueueRender/process → TodoItems.render maps keyed li nodes → diffChildren matches/inserts or unmounts children.
- Hook state update: useState delegates to useReducer → dispatch computes nextValue and compares Object.is → component.setState({}) schedules an update → options._render applies _nextValue → the component renders with its new hook value.
- Hydration: hydrate sets MODE_HYDRATE → render ignores the previous VNode root and supplies existing DOM children → diffElementNodes claims matching nodes or creates missing ones → function-valued props attach handlers → commitRoot completes mounting.
- Lazy loading: Lazy invokes loader once and throws its pending promise → diff catches and calls options._catchError → the Suspense wrapper locates _childDidSuspend → the boundary schedules fallback output → promise settlement restores parent state and force-updates suspenders.
- Suspended hydration: diff records suspension flags and a start marker without discarding claimed markup → promise settlement schedules retry → diff rescans nested $s and /$s comment markers → resumed rendering removes only retained DOM it did not claim.
- Portal flow: createPortal creates a Portal VNode carrying _parentDom → diff switches container and namespace, resets hydration inputs, and calls diffChildren there → it clears the portal's host _dom and restores the host insertion cursor.
- People loading/navigation: App.componentDidMount → store.loadUsers → fetch/json/map → users.replace → observer render generates profile links → Link.handleClick → Router.navigate/history.pushState → nested Route renders Profile.
- Unmount: render(null, container) removes unmatched children → unmount invokes options.unmount, ref cleanup, and componentWillUnmount → it recursively removes DOM and clears ownership/listeners; hooks defer passive cleanup through their after-paint queue.
Testing signals
Tests and CI were inspected, not executed; no passing result, coverage percentage, or benchmark outcome is asserted. Vitest divides node/shared tests from browser suites driven by headless Chromium through Playwright. The configuration can test source or minified bundles, while separate TypeScript commands check declarations. Inspected tests cover DOM output and operation counts, hydration, component construction, suspense, effects, diagnostics, and serialization guards. The inventory and sampled test reading are bounded rather than exhaustive, and explicit skips identify gaps.
- Vitest uses global test APIs and a node/shared project plus browser/shared suites for core, debug, devtools, hooks, compat, test-utils, and jsx-runtime.
- Browser tests use the Playwright provider with one headless Chromium instance; this configuration does not define Firefox or WebKit instances.
- MINIFY=true selects dist aliases and COVERAGE=true enables V8 reports in HTML, LCOV, and text-summary formats; tests transform private property names using mangle.json.
- Core render tests assert text/element transitions and template content reuse; Fragment tests record DOM operation sequences, and component tests check class/function invocation arguments.
- Hydration tests assert textarea synchronization, existing-DOM reuse, zero mutation logs for matching markup, and event activation after hydration; portal tests assert host-node identity and independent cleanup.
- Suspense tests control promise resolution to assert fallback-to-content behavior; suspense-hydration tests assert unchanged markup and no DOM operations while suspended.
- useEffect tests assert pending-effect cancellation on unmount and cleanup-before-create ordering; act tests assert options restoration and flushing of effects and event-triggered updates.
- Debug tests spy on console output, verify devtools attachment, and reject invalid render parents/types; the node suite checks core build exports.
- Security-relevant regression assertions reject JSON-shaped VNode injection and verify escaping of dynamic JSX attribute/child values; their existence is not evidence that they pass at this commit.
- Core and compat declaration checks use strict TypeScript configurations; DOM declaration fixtures include @ts-expect-error checks for invalid ARIA roles and signal-wrapped attributes.
- Explicitly skipped tests concern updating suspended children and successfully unmounting a constantly throwing ref; they cannot supply active regression protection.
- The inspected build-test workflow specifies frozen installation, build, lint, test:unit with coverage, Coveralls reporting, and packaging without pack lifecycle scripts; none of these steps was executed during this investigation.
Risk map
The security-sensitive runtime boundaries inspected are raw HTML assignment, DOM attributes/events, VNode identity checks, compiler serialization overrides, and the devtools attachment hook. Renderer correctness also depends on cross-package property mappings and careful coordination of suspension, hydration, portals, refs, and effects. Tests contain explicit skips, and workflow source exposes concrete wiring and artifact-handling concerns. These are source observations or labeled hypotheses, not confirmed vulnerabilities or reproduced runtime failures; no whole-repository absence of auth, IPC, secrets, or other integrations is claimed.
- dangerouslySetInnerHTML assigns newHtml.__html directly to dom.innerHTML without sanitization in this path; applications must control the supplied HTML trust boundary.
- setProperty writes DOM properties or attributes directly, including href through the attribute route; no URL-scheme validation appears in this function.
- The renderer rejects VNodes whose constructor is not undefined, and both factories establish that marker; changing the marker or coercion logic touches the documented JSON-injection defense.
- jsxAttr accepts a string returned by options.attr before default entity encoding, so custom serializers control a raw serialized-HTML output boundary.
- Devtools attachment invokes a global __PREACT_DEVTOOLS__.attachPreact with shared options and component primitives; that bridge assumes the installed global hook is trusted.
- Private properties shared by independently built bundles require stable mangle mappings; the build warns about newly mangled properties lacking cache entries, making mapping changes a cross-addon compatibility hotspot.
- Hooks, debug, compat normalization, and Suspense all replace callbacks on the same options object while retaining previous callbacks; integration behavior depends on preserving those chains.
- Hypothesis: suspension/hydration/portal edits have a broad correctness impact because marker rescanning, DOM cursors, alternate containers, retained hook state, and cleanup routing interact across core and addons. (inferred)
- Three inspected suspended-child update cases and a throwing-ref unmount case are skipped; this is an explicit regression-coverage gap, not proof of current failure.
- Compat transition APIs do not provide concurrent scheduling: startTransition calls immediately, useDeferredValue returns its input, useTransition reports false, and useInsertionEffect aliases useLayoutEffect.
- The manual single-benchmark workflow calls ci.yml as a reusable workflow with ref/artifact_name inputs, but ci.yml declares no workflow_call trigger; it also renames the local tarball before a subsequent rm -rf * step.
- People Browser consumes external Random User JSON without an explicit HTTP status check before parsing/model insertion; malformed responses or model incompatibility can interrupt this demo flow.
Extension points
Preact's main extension mechanism is the shared options object, rather than an application plugin registry. Renderer callbacks let addons intercept VNode creation, rendering, commits, errors, events, and teardown. Components, context providers, memo comparators, lazy loaders, and external-store subscribers supply narrower behavior contracts. Packaging and demo routes have explicit lists that must be updated when adding a new surface.
- Public Options declares vnode, unmount, diffed, event, requestAnimationFrame, debounceRendering, debug-value, hook-name, and attribute-serialization hooks.
- Internal Options adds _root, _diff, _commit, _render, _hook, _skipEffects, _catchError, and _hydrationMismatch contracts.
- Hooks demonstrates callback composition by capturing old options handlers and delegating to them; extensions should follow this existing chaining contract.
- options.debounceRendering overrides component queue scheduling, and options.requestAnimationFrame overrides passive-effect flushing.
- Component classes extend lifecycle and error-boundary behavior through render, shouldComponentUpdate, getChildContext, getDerivedStateFromError, and componentDidCatch.
- memo accepts a custom equality comparator; lazy accepts an asynchronous loader resolving to a default export or component.
- useSyncExternalStore integrates external state through subscribe/getSnapshot/getServerSnapshot callbacks and uses the subscription return value as effect cleanup.
- options.attr can customize compiler-generated attribute serialization, and addHookName forwards labels through options._addHookName.
- A new shipped addon must join PACKAGES and supply source/module manifest metadata; the root exports and files lists determine consumer resolution and tarball inclusion.
- New demo surfaces plug into imports, navigation links, and Router children in demo/index.jsx; the People router additionally accepts Route component or render callbacks.
- Type extensions operate through exported VNode/component/attribute interfaces and SignalLike/Signalish contracts; declaration fixtures exercise custom typed DOM attributes.
Contributor handoff
This brief is tied to the pinned commit and should be revalidated against any later checkout. Tests and CI were inspected, not executed; suggested commands below are future validation guidance, not completed checks. The investigation sampled source and tests extensively but does not establish exhaustive coverage or confirmed vulnerabilities. Keep edits localized to the relevant core/addon contract, then consider declarations, VNode factories, property mappings, and bundle behavior where those contracts cross boundaries.
- Read package.json, CONTRIBUTING.md, and workspace configuration first to establish package boundaries, pnpm/Node versions, scripts, and dependency policy; addon manifests are not separate workspace projects.
- For rendering changes, follow src/index.js → render.js → diff/index.js → diff/children.js; the root wrapper, previous tree, recursive diff, and commit queues form the central edit boundary.
- Keep the classic and automatic JSX VNode factories synchronized when changing internal shape or ref behavior, including the undefined constructor marker.
- Treat _children, _parent, _depth, _index, _dom, and _flags as coordinated renderer metadata; child matching temporarily uses _index before assigning the final position.
- Read component queue scheduling and hooks before changing batching; enqueueRender assumes asynchronous scheduling, and pending hook values are promoted by options._render.
- Read Suspense with core hydration and portal branches before editing async rendering; parked hook state, refs, DOM containers, and stream markers span multiple modules.
- Preserve previous options callbacks when extending addon hooks, and restore test scheduler overrides; setupRerender/act/teardown provide the established controls.
- Cross-bundle private-field changes require reviewing mangle.json and build warnings; minified test aliases and property-renaming transforms are intended to exercise that interoperability.
- When execution is authorized, use the relevant file-filtered test:vitest invocation first; declaration changes call for test:ts:core or test:ts:compat, and dist validation requires build before test:vitest:min. These scripts and CI were inspected, not executed here.
- Do not equate the tsc lint command with full runtime-JavaScript checking: jsconfig-lint.json sets checkJs=false and limits its included surfaces; separate strict configs check core and compat declaration fixtures.
- Follow formatting conventions of tabs, single quotes, semicolons, no trailing commas, and 80-column print width; use existing oxfmt/oxlint scripts.
- Read source when contributor prose drifts: CONTRIBUTING describes options.js as an empty object, but the inspected file initializes _catchError; compat/debug peer metadata also still targets preact ^10.0.0 despite the root 11.0.0 version.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 202 | 81% |
| TypeScript | 41 | 16% |
| JSON | 22 | docs/config |
| YAML | 9 | docs/config |
| Sass | 7 | 3% |
| Markdown | 6 | docs/config |
| CSS | 1 | docs/config |
| HTML | 1 | docs/config |
Start reading here
Probable source entrypoint: src/index.js — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (17 files)
Source layout — src/
| Path | Files |
|---|---|
src/diff/ | 4 |
src/component.js | 1 |
src/constants.js | 1 |
src/create-context.js | 1 |
src/create-element.js | 1 |
src/create-portal.js | 1 |
src/dom.d.ts | 1 |
src/index.d.ts | 1 |
src/index.js | 1 |
src/internal.d.ts | 1 |
src/jsx.d.ts | 1 |
src/options.js | 1 |
src/render.js | 1 |
src/util.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
compat/ | 79 |
test/ | 57 |
demo/ | 52 |
hooks/ | 23 |
debug/ | 22 |
src/ | 17 |
.github/ | 12 |
jsx-runtime/ | 7 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — preact v11.0.0, 24 declared dependencies.
@babel/core@babel/preset-env@rollup/plugin-babel@types/chai@types/node@vitest/browser@vitest/browser-playwright@vitest/coverage-v8babel-plugin-transform-rename-propertieschaicross-envhusky
CI & config entrypoints
README.md— Repository readmedemo/vite.config.js— Vite config.github/workflows/release.yml— GitHub Actions workflow.github/workflows/single-bench.yml— GitHub Actions workflow.github/workflows/run-bench.yml— GitHub Actions workflow.github/workflows/pr-reporter.yml— GitHub Actions workflow.github/workflows/benchmarks.yml— GitHub Actions workflow.github/workflows/size.yml— GitHub Actions workflow.github/workflows/build-test.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow
Structural health signals
Average score 7.4/10 across 96 analyzed source files; 14 hotspots surfaced.
test/browser/refs.test.jsx— 554 lines, score 6 (Large file, Deep nesting)test/browser/fragments.test.jsx— 3318 lines, score 6.2 (Large file, Long function/block)src/dom.d.ts— 2244 lines, score 6.2 (Large file, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
45728eb4315b2026-10-02 — Merge pull request #5292 from piotr-cz/patch-1077c00a721322026-10-02 — Change repository field to object format3fcc391adc242026-09-30 — Merge pull request #5282 from preactjs/JoviDeCroock/compat-server-typesccd48784806a2026-09-30 — Merge branch 'main' into JoviDeCroock/compat-server-typese6ec2da5673e2026-09-30 — Merge pull request #5266 from preactjs/11.0.0