Skip to content

docs(core): improve Signals conceptual guidance#69378

Open
LuEsc wants to merge 5 commits into
angular:mainfrom
LuEsc:docs/signals-overview-improvements
Open

docs(core): improve Signals conceptual guidance#69378
LuEsc wants to merge 5 commits into
angular:mainfrom
LuEsc:docs/signals-overview-improvements

Conversation

@LuEsc

@LuEsc LuEsc commented Jun 16, 2026

Copy link
Copy Markdown

PR Checklist

Please check if your PR fulfills the following requirements:

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.

@pullapprove pullapprove Bot requested a review from JeanMeche June 16, 2026 16:31
@angular-robot angular-robot Bot added area: docs Related to the documentation area: core Issues related to the framework runtime labels Jun 16, 2026
@ngbot ngbot Bot added this to the Backlog milestone Jun 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: core Issues related to the framework runtime area: docs Related to the documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant