GO — Healthy across the board

• Used by 2 trusted projects: remix-run/remix, withastro/astro
• Last commit 1d ago
• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard}

Preact is a 4kB JavaScript framework that provides React's modern API (hooks, functional components, JSX) with a lightweight Virtual DOM implementation optimized for performance. It's a drop-in alternative to React for projects where bundle size matters, with an optional preact/compat layer in the /compat directory that provides near-complete React API compatibility by aliasing React imports to Preact. Monorepo structure with core Preact logic in src/ and preact/ entry point, paired with a React compatibility shim in compat/src/ that re-exports and adapts React APIs. The compat layer provides JSX runtime bridges (compat/jsx-runtime.js), hook adapters (compat/src/hooks.js), and component wrappers (compat/src/forwardRef.js, compat/src/memo.js). Multiple output formats per package (CJS .js, ESM .mjs, UMD .umd.js) via build process.

JavaScript developers building interactive web applications who want React's familiar patterns and ecosystem without React's 40kB+ bundle size overhead. Specifically targets developers working on performance-critical applications, progressive web apps, mobile web, and situations with bandwidth/memory constraints.

Production-ready and actively maintained. The repository shows active CI/CD workflows (build-test.yml, benchmarks.yml, release.yml), comprehensive test coverage tracking via coveralls badges, and detailed GitHub issue templates. Currently on a major version branch (v11+) with v10.x maintained separately, indicating long-term support strategy. Last activity visible in workflow configs suggests ongoing development.

Low risk for core use—Preact has minimal peer dependencies (only peerDependencies on itself in compat), extensive test infrastructure, and a focused scope limiting surface area for bugs. Main risk is in the compat layer's React compatibility claims: while comprehensive, some advanced React features may have subtle behavioral differences. The monorepo approach (core + compat + examples) spreads maintenance load but compat adds complexity.

Active development on the v11 branch with ongoing performance and compatibility work. The GitHub workflows for benchmarks.yml and size.yml indicate continuous monitoring of bundle size and rendering performance—critical concerns for a framework positioning itself as lightweight. PR workflows and benchmark runs suggest feature/optimization PRs are regularly reviewed against performance regressions.

git clone https://github.com/preactjs/preact.git
cd preact
npm install
npm test

Then npm run build to generate dist/ artifacts. Development typically happens in src/ for core and compat/src/ for compatibility layer.

Daily commands:

npm test              # Run test suite
npm run build         # Build dist/ outputs
npm run dev           # Development mode (if configured)
npm run bench         # Run performance benchmarks

Check package.json in root and compat/package.json for full script list. Most development uses the monorepo root scripts.

• src/index.js — Main Preact entry point defining core h(), Component, render(), and fragment APIs that power the virtual DOM engine.
• src/diff/index.js — Core diffing algorithm that reconciles virtual DOM changes to the actual DOM—performance critical for rendering.
• src/create-element.js — JSX transpilation target (h/createElement function) that constructs virtual DOM nodes from component declarations.
• compat/src/index.js — React compatibility layer bridging Preact to React API expectations for class components, hooks, and ecosystem tools.
• src/render.js — Renders virtual DOM to the real DOM and manages component lifecycle, mounting, and unmounting logic.
• babel.config.js — Configures JSX transformation and code optimization pipeline for development and production builds.

• h(type, props, ...children) (Preact core, Babel JSX transpiler) — Creates a vnode object from JSX or direct function calls.
  • Failure mode: Invalid vnode tree; props not passed to children; JSX syntax errors.
• Component (class base) (src/component.js, src/render.js) — Manages lifecycle (mount, update, unmount) and setState for class-based components.
  • Failure mode: Lifecycle hooks not called; state updates lost; memory leaks from uncleared timers.
• Reconciliation engine (diff/index.js) (src/diff/*, src/render.js) — Walks vnode trees and schedules DOM updates via keyed child matching and prop comparison.
  • Failure mode: Wrong DOM updates; reordered list items; stale event handlers; O(n²) child matching without keys.
• Hook state (src/hooks/) (src/hooks/index.js, src/component.js) — Maintains per-component closure state for useState, useEffect, useContext, etc.
  • Failure mode: Hook call order mismatch; stale closures; dependency arrays not checked; memory leaks.
• React compat layer (compat/src/) (compat/src/*, preact core) — Bridges Preact to React API (createElement, Fragment, memo, forwardRef, hooks wrappers).
  • Failure mode: Incompatible React libraries fail; context not propagated; memoization not working; type mismatches.
• render(vnode, container) (src/render.js, src/diff/index.js) — Top-level entry point; mounts/updates component tree and returns root component instance.
  • Failure mode: App not mounted; partial renders; DOM not cleared; hydration failing.
• Debug mode (debug/src/) (debug/src/debug.js, src/component.js) — Adds development warnings for prop mutations, missing keys, and invalid lifecycle usage.
  • Failure mode: Silent bugs in production (no dev warnings); false positives in strict mode.

• User code (Component) → h(type, props, children) — Developer calls h() or writes JSX, creating a vnode descriptor.
• Vnode tree → render(vnode, container) — Application passes root vnode to render(), triggering initial mount or update.
• render() → Reconciliation (diff/index.js) — Renderer walks old and new vnode trees, computing minimal DOM mutations.
• Reconciliation → Real DOM + Hook state — Patches attributes, children, events; calls lifecycle hooks; updates functional component state.
• User event (DOM) → Event handler + setState() — Browser fires event; handler calls setState or hook update, scheduling re-render.
• setState() / hook update → render() (re-render cycle) — State change triggers re-render; cycle repeats from step 2.

Add a new hook to Preact

1. Create hook module in src/hooks/ (e.g., use-my-hook.js) (src/hooks/)
2. Implement hook using __c (component) and __H (hook state) internals (src/hooks/index.js)
3. Export from src/hooks/index.js (src/hooks/index.js)
4. Add React compat wrapper in compat/src/hooks.js if needed (compat/src/hooks.js)
5. Add tests in compat/test/browser/ and src/tests/ (compat/test/browser/)

Add a new compatibility shim to preact/compat

1. Create source module in compat/src/ (e.g., my-shim.js) (compat/src/)
2. Export from compat/src/index.js and compat/src/index.d.ts (compat/src/index.js)
3. Add TypeScript types in compat/src/index.d.ts (compat/src/index.d.ts)
4. Create test file in compat/test/browser/ (compat/test/browser/)

Fix a rendering or diffing bug

1. Locate issue in src/diff/index.js (main) or src/diff/children.js (keying) (src/diff/index.js)
2. Add regression test in src/tests/ with minimal repro (src/__tests__/)
3. Patch diff logic to handle new case (src/diff/index.js)
4. Run yarn test and yarn build to verify no regressions (package.json)

• Virtual DOM with h()/JSX — Provides declarative component model matching React API while enabling efficient diffing.
• Synchronous diffing (no scheduler by default) — Keeps core small (~3kB); optional scheduler can be injected for async rendering.
• Hooks via closure over component fiber — Enables functional components with state without class boilerplate; integrates with existing Component class.
• preact/compat alias layer — Bridges Preact to React ecosystem without forking code; allows drop-in replacement for React.
• Babel JSX transpilation — Transforms JSX → h() calls at build time; minimal runtime overhead.

• Synchronous rendering by default (no time-slicing)

  • Why: Simplifies core; smaller bundle size.
  • Consequence: Long render phases may block main thread; apps needing interruptibility must use external scheduler.

• Single vnode children array (vs Fiber architecture)

  • Why: Easier to understand and debug; fewer allocations.
  • Consequence: Cannot pause/resume renders mid-tree; some concurrent features (Suspense) require workarounds.

• Preact/compat as optional polyfill layer (not core)

  • Why: Keeps core lean; only pay compatibility cost if you need React API.
  • Consequence: Developers must consciously import preact/compat; naive React code may not work with preact main.

• No built-in state management (Redux, Zustand are external)

  • Why: Preact focuses on rendering; state libraries are orthogonal.
  • Consequence: Complex apps must add external state solution; no batteries-included experience like Next.js.

• Server-side rendering (SSR) support in core (hydration exists, but no native SSR APIs)
• Time-slicing or priority-based scheduling (opt-in via external scheduler)
• Automatic code-splitting or lazy-loading (delegated to bundlers)
• Real-time or streaming updates (sync-only rendering model)

• Avg cyclomatic complexity: ~6 — Core diff/reconciliation is O(n) in typical cases but has O(n²) worst-case for unkeyed lists; hooks are O(n) linear scan; most files are straightforward.
• Largest file: src/diff/index.js (350 lines)
• Estimated quality issues: ~3 — Tight coupling between diff/render/component; some internal state mutations; limited test coverage for edge cases in reconciliation.

• Direct DOM mutation in components (High) — Any component calling element.innerHTML or appendChild outside render: Bypasses vnode tree; causes reconciliation bugs and memory leaks when component re-renders.
• Hook call order dependency without stable keys (High) — src/hooks/index.js, user components: Conditional hooks or dynamic hook counts cause stale closures and state leaks.
• Forgetting dependencies in useEffect (Medium) — compat/src/hooks.js, user code: Effect runs on every render instead of only when deps change; causes infinite loops or stale data.
• Missing keys in dynamic lists (High) — src/diff/children.js diffing logic: Unkeyed list reorders trigger incorrect component state and DOM node reuse.
• Mutating vnode props or state directly (Medium) — User components, src/component.js: React/Preact do not detect mutations; next render uses stale values.

• src/diff/children.js (Algorithmic complexity) — Unkeyed child lists require O(n²) comparison in worst case; keying reduces to O(n) but adds overhead.
• src/diff/index.js reconciliation loop (Concurrency / interactivity) — Synchronous diffing blocks main thread on large trees; no time-slicing or priority queueing.
• Hook state closure (src/hooks/index.js) (Algorithmic complexity) — Linear scan of hook list; O(n) lookup per hook; no optimization for sparse hook usage.
• compat/src/ React shims (Bundle size / startup) — Each compat shim adds wrapper overhead (memo, forwardRef); not tree-shaken if unused.

No hidden traps for basic setup, but note: (1) The compat package has a peerDependency on preact ^10.0.0, so you must install core Preact separately before using compat—it's not a standalone React replacement out of the box. (2) The monorepo uses npm workspaces or similar (inferred from multiple package.json files); running npm install in compat/ alone may fail. (3) The size.yml workflow suggests strict bundle size limits are enforced; PR changes to core files may fail CI if they exceed the 4kB threshold. (4) TypeScript definitions are split across multiple .d.ts files (src/index.d.ts, compat/src/index.d.ts, compat/src/internal.d.ts)—ensure type exports match your changes.

• Virtual DOM diffing algorithm — Preact's entire value proposition rests on a highly optimized diff implementation; understanding the reconciliation strategy in src/diff/index.js is essential to modifying rendering behavior
• JSX/h() transformation — Preact uses createElement (aliased as h()) to transform JSX into VDOM objects; the babel.config.js and compat/jsx-runtime.js show how this transformation works across different JSX syntax versions
• Hooks (useState, useEffect, useContext) — Modern Preact is function-component based with hooks; compat/src/hooks.js implements React's hooks API, making them core to writing and understanding Preact code
• Fiber architecture — While Preact doesn't use React's fiber architecture explicitly (it uses a simpler incremental reconciliation model), understanding why Preact avoids fibers explains its size advantage and batch update strategy
• Hydration (server-to-client) — The README mentions 'seamless hydration from Server Side Rendering'; the diff algorithm must intelligently match pre-rendered DOM to VDOM without full re-render—this is a non-obvious challenge in the codebase
• Component memoization (React.memo pattern) — compat/src/memo.js implements React's memo wrapper; understanding memoization strategy and when Preact skips re-renders is key to performance optimization in apps
• Polymorphic component rendering (h/createElement overloads) — Preact's h() function handles both HTML elements (strings like 'div') and component functions; the TypeScript overloads in index.d.ts show this polymorphism is intentional and complex

• facebook/react — The original framework Preact is designed as a lightweight alternative to; understanding React's patterns helps contextualize Preact's design tradeoffs
• preactjs/preact-cli — Official CLI tool for scaffolding and building Preact projects; the standard way developers initialize Preact apps
• preactjs/preact-render-to-string — Server-side rendering package for Preact; essential for full-stack apps using Preact + SSR mentioned in the README
• infernojs/inferno — Alternative lightweight VDOM framework in the same performance-focused niche; useful for comparing architectural decisions
• developit/htm — Tagged template JSX alternative that works with Preact (mentioned in README); enables Preact usage without a build step

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for compat/src/suspense.js

The suspense.js module is a critical compatibility layer for React's Suspense API, but there's no corresponding test file in compat/test/browser/. Suspense is complex (involving error boundaries, lazy loading, and fallback rendering), and comprehensive tests would prevent regressions and document expected behavior for contributors.

• [ ] Create compat/test/browser/suspense.test.jsx following existing test patterns
• [ ] Add tests for basic Suspense boundary rendering with lazy components
• [ ] Add tests for error handling and fallback UI behavior
• [ ] Add tests for nested Suspense boundaries
• [ ] Add tests for Suspense with hooks (useTransition if applicable)
• [ ] Run tests locally and ensure all pass with 'npm test'

Add integration tests for preact/compat scheduler module with concurrent rendering

The compat/src/scheduler.js module exposes React's scheduler API, but there are no dedicated integration tests verifying it works correctly with Preact's diffing algorithm. Given that the README emphasizes 'Transparent asynchronous rendering', testing scheduler behavior under realistic conditions (component updates, priority changes, bailouts) would be valuable.

• [ ] Create compat/test/browser/scheduler.integration.test.jsx
• [ ] Add tests for task scheduling and prioritization with multiple concurrent updates
• [ ] Add tests for scheduler callbacks with real DOM rendering
• [ ] Add tests for cancelation and rescheduling scenarios
• [ ] Verify scheduler doesn't block rendering in high-frequency update scenarios
• [ ] Document expected performance characteristics in test comments

Create missing unit tests for compat/src/render.js and hydration edge cases

The render.js module handles SSR hydration, which the README highlights as a key feature ('Highly optimized diff algorithm and seamless hydration from Server Side Rendering'). While hydrate.test.jsx exists, there are no dedicated tests for the main render.js module's edge cases (partial hydration, mismatched markup, concurrent hydration), which are critical for production reliability.

• [ ] Create compat/test/browser/render.integration.test.jsx for render.js-specific scenarios
• [ ] Add tests for hydrating pre-rendered content with exact DOM matching
• [ ] Add tests for hydration with dynamic content and data attributes
• [ ] Add tests for handling markup mismatches between server and client renders
• [ ] Add tests for hydrating multiple Preact roots on the same page
• [ ] Verify hydration performance doesn't regress with npm run bench

• Add missing TypeScript tests for compat/src/portals.js—the Portal implementation exists but no test file is evident in the file list; writing comprehensive tests for edge cases (unmounting portals, nested portals, SSR hydration) would be valuable.
• Expand JSX runtime error messages in compat/jsx-runtime.js with React-compatible stack traces for development mode—currently Preact's JSX may produce less helpful dev errors than React, improving DX for developers using compat.
• Document the scheduler API mentioned in the README ('pluggable scheduler') by adding example usage and Preact-specific scheduler implementations to the examples/ directory or compat/test-utils.js.

The Preact codebase demonstrates a solid security posture with no critical vulnerabilities identified. The codebase follows good practices with clear licensing, code of conduct, and contribution guidelines. The main observations are: (1) No hardcoded secrets or credentials detected in the provided file structure; (2) Dependency surface is minimal with only peer dependencies on preact; (3) No obvious injection vulnerabilities in the visible configuration files; (4) No Docker/infrastructure issues identified. Recommendations focus on enhancing security documentation and policies, which are standard practices for open-source projects.

• Low · Missing dependency version pinning in peer dependencies — compat/package.json - peerDependencies. The package.json uses a caret range (^10.0.0) for the preact peer dependency, which allows breaking changes in minor versions. While this is standard practice for peer dependencies, it could allow incompatible versions to be installed. Fix: Consider documenting compatibility requirements clearly. For peer dependencies, caret ranges are acceptable but ensure comprehensive testing across supported versions.
• Low · No security policy or security.md file — Root directory - missing SECURITY.md. The repository does not appear to have a SECURITY.md file documenting security policies, vulnerability reporting procedures, or security contact information based on the provided file structure. Fix: Create a SECURITY.md file at the repository root with guidelines for reporting security vulnerabilities responsibly, supported versions, and security contact information.
• Low · No explicit Content Security Policy enforcement documentation — Root directory / Documentation. As a UI framework, Preact handles JSX and virtual DOM rendering. While the file structure doesn't show obvious XSS vulnerabilities, there's no documented security guidance for developers about safe usage patterns. Fix: Add security best practices documentation in README or CONTRIBUTING.md covering: safe JSX usage patterns, avoiding dangerouslySetInnerHTML where possible, and proper input sanitization.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/preactjs/preact shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live preactjs/preact repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/preactjs/preact.

What it runs against: a local clone of preactjs/preact — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in preactjs/preact | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of preactjs/preact. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/preactjs/preact.git
#   cd preact
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of preactjs/preact and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "preactjs/preact(\\.git)?\\b" \\
  && ok "origin remote is preactjs/preact" \\
  || miss "origin remote is not preactjs/preact (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/index.js" \\
  && ok "src/index.js" \\
  || miss "missing critical file: src/index.js"
test -f "src/diff/index.js" \\
  && ok "src/diff/index.js" \\
  || miss "missing critical file: src/diff/index.js"
test -f "src/create-element.js" \\
  && ok "src/create-element.js" \\
  || miss "missing critical file: src/create-element.js"
test -f "compat/src/index.js" \\
  && ok "compat/src/index.js" \\
  || miss "missing critical file: compat/src/index.js"
test -f "src/render.js" \\
  && ok "src/render.js" \\
  || miss "missing critical file: src/render.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/preactjs/preact"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.