Public API Surface Management

Relevant source files

• adev/src/content/guide/forms/signals/form-submission.md
• adev/src/content/guide/signals/debounced.md
• goldens/public-api/common/http/index.api.md
• goldens/public-api/common/index.api.md
• goldens/public-api/common/upgrade/index.api.md
• goldens/public-api/core/index.api.md
• goldens/public-api/core/rxjs-interop/index.api.md
• goldens/public-api/forms/signals/compat/index.api.md
• goldens/public-api/forms/signals/index.api.md
• goldens/public-api/router/index.api.md
• packages/animations/browser/src/dsl/animation_ast.ts
• packages/animations/src/version.ts
• packages/common/http/src/resource.ts
• packages/common/http/src/resource_api.ts
• packages/common/http/test/resource_spec.ts
• packages/common/src/directives/ng_component_outlet.ts
• packages/common/src/directives/ng_for_of.ts
• packages/common/src/directives/ng_if.ts
• packages/common/src/directives/ng_switch.ts
• packages/common/src/directives/ng_template_outlet.ts
• packages/common/src/location/hash_location_strategy.ts
• packages/common/src/location/util.ts
• packages/common/test/BUILD.bazel
• packages/common/test/directives/ng_class_spec.ts
• packages/common/test/directives/ng_component_outlet_spec.ts
• packages/common/test/directives/ng_if_spec.ts
• packages/common/test/directives/ng_plural_spec.ts
• packages/common/test/directives/ng_style_spec.ts
• packages/common/test/directives/ng_switch_spec.ts
• packages/common/test/directives/ng_template_outlet_spec.ts
• packages/common/test/directives/non_bindable_spec.ts
• packages/common/test/pipes/json_pipe_spec.ts
• packages/common/test/pipes/slice_pipe_spec.ts
• packages/common/testing/src/mock_location_strategy.ts
• packages/core/primitives/di/BUILD.bazel
• packages/core/primitives/dom-navigation/BUILD.bazel
• packages/core/primitives/dom-navigation/src/navigation_types.ts
• packages/core/primitives/dom-navigation/testing/BUILD.bazel
• packages/core/primitives/dom-navigation/testing/fake_navigation.ts
• packages/core/primitives/dom-navigation/testing/test/BUILD.bazel
• packages/core/primitives/dom-navigation/testing/test/fake_platform_navigation.spec.ts
• packages/core/primitives/event-dispatch/BUILD.bazel
• packages/core/primitives/event-dispatch/contract_binary.ts
• packages/core/primitives/event-dispatch/test/BUILD.bazel
• packages/core/rxjs-interop/BUILD.bazel
• packages/core/rxjs-interop/src/rx_resource.ts
• packages/core/rxjs-interop/src/to_signal.ts
• packages/core/rxjs-interop/test/BUILD.bazel
• packages/core/rxjs-interop/test/rx_resource_spec.ts
• packages/core/rxjs-interop/test/to_signal_spec.ts
• packages/core/src/authoring.ts
• packages/core/src/change_detection/differs/iterable_differs.ts
• packages/core/src/change_detection/differs/keyvalue_differs.ts
• packages/core/src/core.ts
• packages/core/src/render3/instructions/control.ts
• packages/core/src/render3/interfaces/control.ts
• packages/core/src/resource/api.ts
• packages/core/src/resource/debounce.ts
• packages/core/src/resource/from_snapshots.ts
• packages/core/src/resource/index.ts
• packages/core/src/resource/resource.ts
• packages/core/src/util/promise_with_resolvers.ts
• packages/core/test/resource/debounce_spec.ts
• packages/core/test/resource/resource_snapshot_spec.ts
• packages/core/test/resource/resource_spec.ts
• packages/forms/signals/compat/public_api.ts
• packages/forms/signals/compat/src/api/extract.ts
• packages/forms/signals/compat/src/compat_structure.ts
• packages/forms/signals/src/api/control.ts
• packages/forms/signals/src/api/rules/validation/validate_async.ts
• packages/forms/signals/src/api/structure.ts
• packages/forms/signals/src/api/types.ts
• packages/forms/signals/src/field/context.ts
• packages/forms/signals/src/field/manager.ts
• packages/forms/signals/src/field/node.ts
• packages/forms/signals/src/field/resolution.ts
• packages/forms/signals/src/field/structure.ts
• packages/forms/signals/src/field/submit.ts
• packages/forms/signals/src/field/validation.ts
• packages/forms/signals/src/schema/logic.ts
• packages/forms/signals/src/schema/logic_node.ts
• packages/forms/signals/src/schema/schema.ts
• packages/forms/signals/test/node/compat/extract_value.spec.ts
• packages/forms/signals/test/node/field_context.spec.ts
• packages/forms/signals/test/node/field_node.spec.ts
• packages/forms/signals/test/node/logic_node.spec.ts
• packages/forms/signals/test/node/resource.spec.ts
• packages/forms/signals/test/node/submit.spec.ts
• packages/forms/signals/test/node/types.spec.ts
• packages/forms/signals/test/node/validation_status.spec.ts
• packages/forms/signals/test/web/compat_form.spec.ts
• packages/forms/signals/test/web/debounce_async_validation_bug.spec.ts
• packages/forms/signals/test/web/dynamic_binding.spec.ts
• packages/forms/signals/test/web/focus.spec.ts
• packages/forms/signals/test/web/orphan_repro.spec.ts
• packages/router/src/directives/router_link.ts
• packages/router/src/events.ts
• packages/router/src/index.ts
• packages/router/src/models.ts
• packages/router/src/navigation_transition.ts
• packages/router/src/router.ts
• packages/router/src/statemanager/navigation_state_manager.ts
• packages/router/src/statemanager/state_manager.ts
• packages/router/test/computed_state_restoration.spec.ts
• packages/router/test/helpers.ts
• packages/router/test/integration/duplicate_in_flight_navigations.spec.ts
• packages/router/test/integration/eager_url_update_strategy.spec.ts
• packages/router/test/integration/guards.spec.ts
• packages/router/test/integration/integration.spec.ts
• packages/router/test/integration/integration_helpers.ts
• packages/router/test/integration/lazy_loading.spec.ts
• packages/router/test/integration/navigation.spec.ts
• packages/router/test/integration/navigation_errors.spec.ts
• packages/router/test/integration/redirects.spec.ts
• packages/router/test/integration/route_data.spec.ts
• packages/router/test/integration/route_reuse_strategy.spec.ts
• packages/router/test/integration/router_events.spec.ts
• packages/router/test/integration/router_link_active.spec.ts
• packages/router/test/integration/router_links.spec.ts
• packages/router/test/regression_integration.spec.ts
• packages/router/test/router_link_spec.ts
• packages/router/test/router_preloader.spec.ts
• packages/router/test/with_platform_navigation.spec.ts

Purpose and Scope

This document describes Angular's public API surface management system, which uses "golden files" to track and validate the public API of framework packages. These files serve as a source of truth for API stability, enabling automated detection of breaking changes before they reach production.

Related Documentation:

• For information about tracking symbols in production bundles, see Bundle Symbol Tracking
• For information about the overall build system, see Build System and Development Infrastructure

---

System Overview

Angular's public API surface management system uses API Extractor to generate machine-readable reports of the public APIs exported from each package. These reports, called "golden files," are checked into version control and validated during CI/CD to prevent accidental breaking changes.

The system operates on the principle that any change to a package's public API must be intentional and reviewed. If a code change modifies the public API surface, the golden files must be updated to reflect this change, making the modification explicit and reviewable.

Key Components:

• API Extractor: Tool that analyzes TypeScript code and generates API reports.
• Golden Files: Generated .api.md files stored in goldens/public-api/.
• Validation Scripts: Build system scripts that compare current API against golden files.
• CI/CD Integration: GitHub Actions workflows that enforce API stability.

Sources: goldens/public-api/core/index.api.md1-10 goldens/public-api/forms/signals/index.api.md1-4

---

Golden File Structure

Repository Organization

File Locations and Contents:

Package	Golden File Path	Description
@angular/core	goldens/public-api/core/index.api.md	Complete public API for core framework goldens/public-api/core/index.api.md1-10
@angular/forms_signals	goldens/public-api/forms/signals/index.api.md	Signal-based reactive forms API goldens/public-api/forms/signals/index.api.md1-5
@angular/router	goldens/public-api/router/index.api.md	Router service and navigation APIs goldens/public-api/router/index.api.md1-5
@angular/common	goldens/public-api/common/index.api.md	Pipes, directives, and location services goldens/public-api/common/index.api.md1-5

Sources: goldens/public-api/core/index.api.md1-10 goldens/public-api/forms/signals/index.api.md1-10 goldens/public-api/router/index.api.md1-5

---

Golden File Format

Structure and Annotations

Golden files are generated in a standardized Markdown format that includes TypeScript declarations annotated with API metadata.

Header Format:

Each golden file begins with a standard header indicating it was generated by API Extractor and should not be edited manually. goldens/public-api/core/index.api.md1-4

API Documentation Tags

API Extractor recognizes several JSDoc-style tags that control API visibility and documentation:

Tag	Purpose	Example in Golden Files
@public	Marks an export as part of the public API	// @public goldens/public-api/core/index.api.md12
@deprecated	Marks an API as deprecated	// @public @deprecated goldens/public-api/core/index.api.md100
// (undocumented)	API element missing documentation	// (undocumented) goldens/public-api/core/index.api.md14

Sources: goldens/public-api/core/index.api.md12-100 goldens/public-api/forms/signals/index.api.md25-107

Type Information

Golden files preserve complete type signatures for all exported entities.

Classes and Methods:

goldens/public-api/core/index.api.md133-159

Functions and Generic Overloads:

goldens/public-api/core/index.api.md40-45

Interfaces and Types:

goldens/public-api/core/index.api.md104-106

---

API Extraction and Validation Flow

Extraction Process

Extraction Steps:

1. TypeScript Analysis: API Extractor parses package entry points (e.g., packages/core/src/core.ts) and follows exports. packages/core/src/core.ts1-15
2. Visibility Filtering: Only @public and @deprecated APIs are included; @internal APIs are excluded.
3. Type Resolution: Full type information is captured, including generic constraints. goldens/public-api/core/index.api.md29-34
4. Report Generation: Output is written to .api.md files in Markdown format. goldens/public-api/core/index.api.md1-5
5. Validation: Generated report is compared against checked-in golden file.

---

Example: Reactive Systems Public API

The management system is critical for new features like Signals and Resources to ensure their public interface remains stable.

Resource API Surface

The resource API in @angular/core is documented as follows:

• Function: resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined> packages/core/src/resource/resource.ts66-67
• Interface: ResourceRef<T> provides signals for value, status, and error. packages/core/src/resource/resource.ts115-134

Signal Forms API Surface

The experimental signal-based forms in @angular/forms_signals expose a large surface area tracked via goldens:

• Field State: FieldState<TValue, TKey> providing WritableSignal<TValue>. goldens/public-api/forms/signals/index.api.md138-151
• Validation: AsyncValidationResult and TreeValidationResult. goldens/public-api/forms/signals/index.api.md44-54

Sources: packages/core/src/resource/resource.ts40-85 goldens/public-api/forms/signals/index.api.md138-151

---

Example: Router Public API

The @angular/router golden file tracks the complex navigation system:

Code Entity	Role	Golden Reference
Router	Main navigation service	packages/router/src/router.ts88
ActivatedRoute	Contains info about the route associated with a component	goldens/public-api/router/index.api.md36
NavigationTransitions	Manages the internal state of navigation	packages/router/src/navigation_transition.ts46
CanActivateFn	Type for route activation guards	goldens/public-api/router/index.api.md130

Sources: goldens/public-api/router/index.api.md36-130 packages/router/src/router.ts88-107

---

API Stability Guarantees

Semantic Versioning

Angular follows semantic versioning for API changes:

Change Type	Version Impact	Golden File Behavior
Add new public API	Minor version	New entries added to golden files
Deprecate API	Minor version	API marked with @deprecated tag
Remove deprecated API	Major version	Entry removed from golden files
Change API signature	Major version	Type signature updated in golden files

Quality Gates

The system automatically detects various types of breaking changes:

1. Removed Exports: APIs removed from public surface.
2. Type Signature Changes: Modified function signatures, class members, or interfaces.
3. Required Parameters: Adding required parameters to existing APIs.
4. Return Type Changes: Modifying return types in incompatible ways.

Sources: goldens/public-api/core/index.api.md100 goldens/public-api/core/index.api.md687

---

Summary

Angular's public API surface management system provides automated protection against unintended breaking changes. By generating machine-readable API reports and validating them in CI/CD, the framework ensures that every modification to the public contract is intentional, documented, and reviewable. The golden files serve as a definitive registry of the framework's promises to its users.

Sources: goldens/public-api/core/index.api.md1-10 goldens/public-api/forms/signals/index.api.md1-10