docs: add new signals tutorial #62750

bencodezen · 2025-07-22T21:51:19Z

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?

Issue Number: N/A

There is no dedicated signals tutorial.

What is the new behavior?

There is now a dedicated signals tutorial! 🎉

Does this PR introduce a breaking change?

Yes
No

Other information

github-actions · 2025-07-22T22:10:13Z

Deployed adev-preview for 5765670 to: https://ng-dev-previews-fw--pr-angular-angular-62750-adev-prev-9coiyqjg.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

...utorials/signals/steps/8-using-signals-with-directives/answer/src/app/highlight-directive.ts

...ials/signals/steps/9-query-child-elements-with-signal-queries/answer/src/app/cart-summary.ts

...rc/content/tutorials/signals/steps/9-query-child-elements-with-signal-queries/src/app/app.ts

kbrilla · 2025-07-23T07:50:14Z

...ent/tutorials/signals/steps/9-query-child-elements-with-signal-queries/answer/src/app/app.ts

+
+  // Query APIs to access child components
+  firstProduct = viewChild(ProductCard);
+  allProducts = viewChild.required(ProductCard, {read: ProductCard});


This is toturial, so I will add that for me most dificult was using viewChild while reading ElementRef with genercis.

For context, this is a known issue #53894

...utorials/signals/steps/8-using-signals-with-directives/answer/src/app/highlight-directive.ts

adev/src/content/tutorials/signals/steps/5-managing-async-signals-with-resources-api/README.md

...ontent/tutorials/signals/steps/3-deriving-state-with-computed-signals/answer/src/app/app.css

jelbourn

got part of the way through, will spend some more time tomorrow

jelbourn · 2025-07-28T23:46:35Z

adev/src/content/tutorials/signals/intro/README.md

+
+## How to use this tutorial
+
+This tutorial assumes you understand Angular's core concepts. If you're new to Angular, read our [essentials guide](/essentials). For coding best practices, see the [Angular style guide](https://angular.dev/style-guide).


I might leave out the reference to the style guide since there's not a whole lot that's related to signals specifically

jelbourn · 2025-07-28T23:52:05Z

adev/src/content/tutorials/signals/steps/1-creating-your-first-signal/README.md

+
+<docs-step title="Configure OnPush change detection">
+Update your component decorator to use `OnPush` change detection strategy. This is essential for components using signals as it optimizes performance by only checking for changes when signals update.
+


What do you think about only having a brief mention of OnPush at the end of this step instead of it being the very first thing?

My thinking is that developers don't really need to know any about it right away, it's more like
"You might notice the ChangeDetectionStrategy.OnPush throughout this tutorial. All you need to know is that this is a performance optimization for Angular components that use signals. Feel free to ignore this for the rest of the signals tutorial."

jelbourn · 2025-07-28T23:58:49Z

adev/src/content/tutorials/signals/steps/1-creating-your-first-signal/README.md

+
+<docs-workflow>
+
+<docs-step title="Import signal function and ChangeDetectionStrategy">


Is it worth having a distinct step for importing symbols? My thinking is that this is more of an aside while going through another step, e.g.

Add a `userStatus` signal to your component class that is initialized with a value of `'offline'` and has types for the common statuses (i.e., online, offline, and away). You can import `signal` from `'@angular/core'`.

jelbourn · 2025-07-29T00:02:14Z

adev/src/content/tutorials/signals/steps/1-creating-your-first-signal/README.md

+  <h1>User Dashboard</h1>
+  <div class="status-indicator" [class]="userStatus()">
+    <span class="status-dot"></span>
+    Status: {{ userStatus() }}


I feel like just showing the signal by itself is maybe a bit too little for a whole step. What do you think about combining this step with the next? For the sake of the tutorial, the second step can probably be simpler- instead of three buttons and three methods, you can just directly call userStatus.set in the template statement (<button (click)="userStatus.set('online')">Go online</button>)

jelbourn · 2025-07-29T00:05:17Z

adev/src/content/tutorials/signals/steps/1-creating-your-first-signal/src/app/app.ts

+    <div class="user-profile">
+      <h1>User Dashboard</h1>
+      <div class="status-indicator offline">
+        <span class="status-dot"></span>


Looking at the current preview on the PR, this status dot doesn't seem to show up?

jelbourn · 2025-07-29T00:07:54Z

...content/tutorials/signals/steps/3-deriving-state-with-computed-signals/answer/src/app/app.ts

+  isAvailable = computed(() => this.userStatus() === 'online');
+
+  statusColor = computed(() => {
+    switch (this.userStatus()) {


I feel like having two different computed expressions that are both switch statements is a bit more repetitive than helpful. I could see having two computed expressions if one was more of a calculation, just to highlight the variety/flexibility of what you can do with computed

jelbourn · 2025-07-29T00:13:42Z

adev/src/content/tutorials/signals/steps/4-deriving-state-with-linked-signals/README.md

@@ -0,0 +1,77 @@
+# Deriving state with linked signals
+
+Now that you've learned [how to derive state with computed signals](/tutorials/signals/3-deriving-state-with-computed-signals), let's explore linked signals. Linked signals are a special type of signal that can be both read and written, while automatically deriving their value from other signals. Unlike computed signals which are read-only, linked signals can be updated directly while maintaining their reactive connection to source signals.


What do you think of starting off by showing a linkedSignal and computed with the same expression, and then showing that linkedSignal is different because it can be directly updated?

jelbourn · 2025-07-29T00:15:48Z

adev/src/content/tutorials/signals/steps/5-managing-async-signals-with-resources-api/README.md

@@ -0,0 +1,106 @@
+# Managing async signals with Resources API


I think we probably wouldn't want to use the term "async signals", since we want to be clear that signals are always synchronous. It's more that resource gives you a pattern for dealing with async data with signal APIs (i.e., the data is async, but the signals are always sync)

jelbourn · 2025-07-29T00:16:42Z

adev/src/content/tutorials/signals/steps/5-managing-async-signals-with-resources-api/README.md

+<docs-workflow>
+
+<docs-step title="Import resource function and API">
+Add `resource` to your existing imports and import the mock API function.


nit: I would say "fake" instead of "mock"

bencodezen added action: review The PR is still awaiting reviews from at least one requested reviewer area: docs Related to the documentation adev: preview labels Jul 22, 2025

ngbot bot added this to the Backlog milestone Jul 22, 2025

kbrilla reviewed Jul 23, 2025

View reviewed changes

otodockal reviewed Jul 23, 2025

View reviewed changes

...utorials/signals/steps/8-using-signals-with-directives/answer/src/app/highlight-directive.ts Outdated Show resolved Hide resolved

bencodezen marked this pull request as ready for review July 24, 2025 14:13

bencodezen force-pushed the docs/signals-tutorial branch from 3bcbb8f to cbb6000 Compare July 28, 2025 11:26

JeanMeche reviewed Jul 28, 2025

View reviewed changes

adev/src/content/tutorials/signals/steps/5-managing-async-signals-with-resources-api/README.md Outdated Show resolved Hide resolved

JeanMeche reviewed Jul 28, 2025

View reviewed changes

...ontent/tutorials/signals/steps/3-deriving-state-with-computed-signals/answer/src/app/app.css Outdated Show resolved Hide resolved

bencodezen force-pushed the docs/signals-tutorial branch 3 times, most recently from cf0c40e to 11e9423 Compare July 28, 2025 14:03

docs: add new signals tutorial

5765670

bencodezen force-pushed the docs/signals-tutorial branch from 11e9423 to 5765670 Compare July 28, 2025 15:07

jelbourn self-requested a review July 28, 2025 15:58

jelbourn reviewed Jul 29, 2025

View reviewed changes


		## How to use this tutorial

		This tutorial assumes you understand Angular's core concepts. If you're new to Angular, read our [essentials guide](/essentials). For coding best practices, see the [Angular style guide](https://angular.dev/style-guide).


		<docs-step title="Configure OnPush change detection">
		Update your component decorator to use `OnPush` change detection strategy. This is essential for components using signals as it optimizes performance by only checking for changes when signals update.


		<docs-workflow>

		<docs-step title="Import signal function and ChangeDetectionStrategy">

		@@ -0,0 +1,77 @@
		# Deriving state with linked signals

		Now that you've learned [how to derive state with computed signals](/tutorials/signals/3-deriving-state-with-computed-signals), let's explore linked signals. Linked signals are a special type of signal that can be both read and written, while automatically deriving their value from other signals. Unlike computed signals which are read-only, linked signals can be updated directly while maintaining their reactive connection to source signals.

		@@ -0,0 +1,106 @@
		# Managing async signals with Resources API

docs: add new signals tutorial #62750

Are you sure you want to change the base?

docs: add new signals tutorial #62750

Uh oh!

Conversation

bencodezen commented Jul 22, 2025

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

Uh oh!

github-actions bot commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

github-actions bot commented Jul 22, 2025 •

edited

Loading