| name | preact-signals-debugging |
| description | Use when diagnosing Preact Signals bugs, stale renders, missing updates, memory leaks, duplicate Preact copies, React transform misses, devtools/debug output, SSR differences, or issues that need a minimal reproduction. |
Preact Signals Debugging
Core Approach
Classify the failure before editing code: core reactivity, Preact adapter, React adapter, no-build/CDN singleton, transform configuration, SSR, or devtools/debugging. Most reported issues reduce to one of those boundaries.
Triage Checklist
- Confirm package names and versions:
@preact/signals-core, @preact/signals, @preact/signals-react, @preact/signals-react-transform, preact, react.
- Check whether the app is Preact or React. The adapters differ.
- Verify the signal write is an assignment to
.value, not deep mutation.
- Verify the subscribed
.value read actually executes at runtime.
- Check whether the value is rendered as
{signal} or {signal.value} and whether direct DOM optimization is expected.
- For React, verify the Babel transform or
useSignals() is present.
- For no-build setups, check duplicate Preact copies.
- For SSR, remember server renders do not track rerender subscriptions.
Fast Symptom Map
| Symptom | Likely Boundary | Next Skill |
|---|
| Effect logs but component does not rerender | Adapter or duplicate Preact | preact-signals-preact-integration or preact-signals-no-build |
| Object field changed but subscribers stale | Core signal semantics | preact-signals-core |
React component reads .value but does not update | React tracking setup | preact-signals-react-integration |
Signal works in text but not checked or disabled | React DOM attribute limitation | preact-signals-react-integration |
For children ignore parent variable changes | Cached utility children | preact-signals-preact-integration |
| CDN example behaves differently from npm | Version drift or duplicate Preact | preact-signals-no-build |
Minimal Reproduction Standard
For upstream issues, require a small StackBlitz, CodeSandbox, CodePen, or repository. Screenshots and built output are not enough when maintainers need to inspect runtime code paths.
Keep the reproduction focused:
- one adapter;
- pinned dependency versions;
- one signal write;
- one observed stale or unexpected render;
- no unrelated app framework unless the bug is framework-specific.
Debug Aids
- Add
preact/debug in Preact apps for development warnings.
- Use
@preact/signals-debug and the devtools packages when debugging graph behavior.
- In React transform work, set
DEBUG=signals:react-transform:* to inspect transform decisions.
- Use browser tests for DOM updater behavior; unit tests can miss adapter integration problems.
References
