docs(core): improve Signals conceptual guidance by LuEsc · Pull Request #69378 · angular/angular
PR Checklist
Please check if your PR fulfills the following requirements:
- The commit message follows our guidelines: https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md
- Tests for the changes have been added (for bug fixes / features)
- Docs have been added / updated (for bug fixes / features)
PR Type
What kind of change does this PR introduce?
- Bugfix
- Feature
- Code style update (formatting, local variables)
- Refactoring (no functional changes, no api changes)
- Build related changes
- CI related changes
- Documentation content changes
- angular.dev application / infrastructure changes
- Other... Please describe:
What is the current behavior?
The Signals overview guide explains the core APIs and reactive concepts, but provides limited guidance on how to reason about Signals when designing applications. The effect guide
documents the API and its lifecycle but does not address how it is commonly misused.
In particular, the guides do not clearly explain:
- The mental model behind Signals as a reactive state graph.
- When to use computed versus effect.
- Why derived state should generally be modeled with computed.
- The conceptual distinction between Signals and RxJS.
- Common misuse patterns with effect, such as using it to derive state or synchronize signals, and why those patterns cause subtle bugs.
Issue Number: N/A
What is the new behavior?
This PR adds conceptual guidance to the Signals overview and effect guides, including:
- A new "Mental model" section in the overview guide.
- Guidance on preferring derivation over synchronization.
- Recommendations for choosing between computed and effect.
- A conceptual comparison between Signals and RxJS focused on use cases rather than APIs.
- A new "Common mistakes" section in the effect guide, covering why using effect for derived state or state synchronization causes subtle bugs, and when effect is actually
appropriate.
The goal is to help developers adopt the Signals programming model more effectively and avoid common architectural misunderstandings.
Does this PR introduce a breaking change?
- Yes
- No
Other information
This is a documentation-only change.