Tutorial Applications

Relevant source files

• CHANGELOG.md
• CHANGELOG_ARCHIVE.md
• adev/shared-docs/components/copy-link-anchor/BUILD.bazel
• adev/shared-docs/components/copy-link-anchor/copy-link-anchor.component.ts
• adev/shared-docs/components/table-of-contents/table-of-contents.component.scss
• adev/shared-docs/components/viewers/docs-viewer/docs-viewer.component.scss
• adev/shared-docs/package.json
• adev/src/app/editor/code-editor/constants/code-editor-extensions.ts
• adev/src/app/editor/code-editor/constants/code-editor-languages.ts
• adev/src/app/editor/code-editor/constants/syntax-styles.ts
• adev/src/app/editor/code-editor/constants/theme-styles.ts
• adev/src/app/features/docs/docs.component.html
• adev/src/app/features/docs/docs.component.scss
• adev/src/app/features/references/api-reference-details-page/api-reference-details-page.component.html
• adev/src/app/features/references/api-reference-details-page/api-reference-details-page.component.scss
• adev/src/app/features/references/api-reference-details-page/api-reference-details-page.component.ts
• adev/src/app/features/references/cli-reference-details-page/cli-reference-details-page.component.html
• adev/src/app/features/references/cli-reference-details-page/cli-reference-details-page.component.scss
• adev/src/app/features/references/cli-reference-details-page/cli-reference-details-page.component.spec.ts
• adev/src/app/features/references/cli-reference-details-page/cli-reference-details-page.component.ts
• adev/src/app/features/references/constants/api-reference-prerender.constants.ts
• adev/src/app/features/references/services/reference-scroll-handler.service.ts
• adev/src/app/features/tutorial/split-resizer-handler.service.ts
• adev/src/app/features/tutorial/tutorial.component.scss
• adev/src/app/features/update/recommendations.ts
• adev/src/app/features/update/update.component.html
• adev/src/app/features/update/update.component.scss
• adev/src/app/features/update/update.component.spec.ts
• adev/src/app/features/update/update.component.ts
• adev/src/content/aria/_build-info.json
• adev/src/content/aria/aria-accordion.json
• adev/src/content/aria/aria-combobox.json
• adev/src/content/aria/aria-grid.json
• adev/src/content/aria/aria-listbox.json
• adev/src/content/aria/aria-menu.json
• adev/src/content/aria/aria-tabs.json
• adev/src/content/aria/aria-toolbar.json
• adev/src/content/aria/aria-tree.json
• adev/src/content/cdk/_build-info.json
• adev/src/content/cdk/cdk_drag_drop.json
• adev/src/content/cdk/cdk_testing.json
• adev/src/content/cdk/cdk_testing_protractor.json
• adev/src/content/cdk/cdk_testing_selenium_webdriver.json
• adev/src/content/cdk/cdk_testing_testbed.json
• adev/src/content/cli/_build-info.json
• adev/src/content/cli/generate.json
• adev/src/content/cli/new.json
• adev/src/content/cli/test.json
• adev/src/content/tutorials/deferrable-views/common/package-lock.json
• adev/src/content/tutorials/deferrable-views/common/package.json
• adev/src/content/tutorials/first-app/common/package-lock.json
• adev/src/content/tutorials/first-app/common/package.json
• adev/src/content/tutorials/homepage/package-lock.json
• adev/src/content/tutorials/homepage/package.json
• adev/src/content/tutorials/learn-angular/common/package-lock.json
• adev/src/content/tutorials/learn-angular/common/package.json
• adev/src/content/tutorials/playground/common/package-lock.json
• adev/src/content/tutorials/playground/common/package.json

Purpose and Scope

This document describes the tutorial applications included in the Angular documentation site (adev). These are standalone Angular applications that demonstrate framework features and provide hands-on learning experiences for users. Each tutorial is a fully-functional Angular application with its own dependencies, build configuration, and source code.

For information about the adev platform architecture and documentation site infrastructure, see Adev Platform Architecture

---

Tutorial Application Structure

The tutorial applications are organized under adev/src/content/tutorials/ with each tutorial in its own directory. These applications serve as the basis for the interactive embedded code editor (Playground) on the Angular.dev site.

Tutorial Name	Path	Description
First App	adev/src/content/tutorials/first-app/	Introductory tutorial for building your first Angular application
Learn Angular	adev/src/content/tutorials/learn-angular/	Comprehensive tutorial covering Angular fundamentals
Playground	adev/src/content/tutorials/playground/	Interactive environment with Material Design components
Homepage	adev/src/content/tutorials/homepage/	Example application for the homepage demonstration
Deferrable Views	adev/src/content/tutorials/deferrable-views/	Tutorial demonstrating @defer block functionality

Each tutorial contains a common/ subdirectory with its own environment configuration:

• package.json - Dependency and script definitions
• package-lock.json - Locked dependency versions for the WebContainer environment
• Source code files (TypeScript, HTML, CSS)
• Angular configuration files

Sources:

• adev/src/content/tutorials/first-app/common/package-lock.json1-30
• adev/src/content/tutorials/playground/common/package-lock.json1-30
• adev/src/content/tutorials/homepage/package-lock.json1-26
• adev/src/content/tutorials/learn-angular/common/package-lock.json1-26
• adev/src/content/tutorials/deferrable-views/common/package-lock.json1-27

---

Package Configuration

Standard Dependencies

All tutorial applications share a common set of Angular framework dependencies. The package-lock.json files currently specify version ^22.0.0-next for all @angular/* packages:

Core Runtime Dependencies:

• @angular/common - Common directives, pipes, and services adev/src/content/tutorials/first-app/common/package-lock.json11
• @angular/compiler - Template compilation adev/src/content/tutorials/first-app/common/package-lock.json12
• @angular/core - Core framework runtime adev/src/content/tutorials/first-app/common/package-lock.json13
• @angular/platform-browser - Browser platform adapter adev/src/content/tutorials/first-app/common/package-lock.json15
• rxjs - Reactive Extensions (~7.8.0) adev/src/content/tutorials/first-app/common/package-lock.json17
• tslib - TypeScript runtime library (^2.3.0) adev/src/content/tutorials/first-app/common/package-lock.json18
• zone.js - Asynchronous operation tracking (~0.16.0) adev/src/content/tutorials/first-app/common/package-lock.json19

Optional Feature Dependencies:

• @angular/forms - Template-driven and reactive forms (found in most tutorials) adev/src/content/tutorials/first-app/common/package-lock.json14
• @angular/router - Navigation and routing (first-app, learn-angular, deferrable-views) adev/src/content/tutorials/first-app/common/package-lock.json16
• @angular/animations - Animation engine (Playground) adev/src/content/tutorials/playground/common/package-lock.json11
• @angular/material - Material Design components (Playground) adev/src/content/tutorials/playground/common/package-lock.json18

Development Dependencies:

• @angular/build - Build system (^22.0.0-next) adev/src/content/tutorials/first-app/common/package-lock.json22
• @angular/cli - Command-line interface (^22.0.0-next) adev/src/content/tutorials/first-app/common/package-lock.json23
• typescript - TypeScript compiler (~5.9.2) adev/src/content/tutorials/first-app/common/package-lock.json26

Sources:

• adev/src/content/tutorials/first-app/common/package-lock.json11-26
• adev/src/content/tutorials/playground/common/package-lock.json11-28
• adev/src/content/tutorials/learn-angular/common/package-lock.json11-25

---

Interactive Update Guide Wizard

The documentation includes an interactive update guide located at adev/src/app/features/update/ This tool helps developers migrate between Angular versions by providing tailored recommendations based on application complexity.

Recommendation Logic

Recommendations are defined in adev/src/app/features/update/recommendations.ts Each recommendation is a Step object containing:

• possibleIn: The version where the change was introduced.
• necessaryAsOf: The version where the change becomes mandatory.
• level: ApplicationComplexity (Basic, Medium, Advanced).
• action: Markdown-formatted instructions for the developer.

Key Recommendation Examples

• Animations Module: Recommends importing BrowserAnimationsModule for apps using animations adev/src/app/features/update/recommendations.ts64-67
• Native Form Validation: Describes the novalidate attribute behavior and how to re-enable native validation via ngNativeValidate adev/src/app/features/update/recommendations.ts72-75
• OpaqueToken Migration: Advises replacing OpaqueToken with InjectionToken adev/src/app/features/update/recommendations.ts118-120

Sources:

• adev/src/app/features/update/recommendations.ts9-33
• adev/src/app/features/update/recommendations.ts35-157

---

Interactive Embedded Code Editor

The adev platform uses an interactive editor powered by WebContainers to run tutorial applications directly in the browser. This system is integrated via the @angular/docs package.

Shared Docs Infrastructure

The shared docs package (adev/shared-docs/package.json) provides the underlying components for the tutorial experience:

• WebContainer API: Used to boot a Node.js-like environment in the browser to run ng serve adev/shared-docs/package.json17
• Syntax Highlighting: Uses shiki for code visualization adev/shared-docs/package.json24
• Diagrams: Uses mermaid for rendering documentation diagrams adev/shared-docs/package.json23
• Compression: Uses fflate for handling compressed tutorial assets adev/shared-docs/package.json20

API Reference Rendering

Tutorials often link to the API reference. The rendering pipeline for these details is handled by ApiReferenceDetailsPage adev/src/app/features/references/api-reference-details-page/api-reference-details-page.component.ts24 It processes JSON metadata generated from the Angular source code (e.g., adev/src/content/aria/aria-menu.json) to display:

• Decorator information (Directive, Component, etc.).
• Member properties and methods (e.g., MenuTrigger.open()) adev/src/content/aria/aria-menu.json117-148
• JSDoc descriptions and code snippets adev/src/content/aria/aria-menu.json188

Sources:

• adev/shared-docs/package.json16-26
• adev/src/content/aria/aria-menu.json1-188
• adev/src/app/features/references/api-reference-details-page/api-reference-details-page.component.ts24-40

---

Content Metadata and Build Info

Tutorials and documentation sections include _build-info.json files to track the source branch and SHA for the content, ensuring the site reflects the correct version of the repository.

• CDK Build Info: adev/src/content/cdk/_build-info.json1-4
• Aria Build Info: adev/src/content/aria/_build-info.json1-4

Sources:

• adev/src/content/cdk/_build-info.json1-4
• adev/src/content/aria/_build-info.json1-4