Bundle Symbol Tracking is a system for monitoring and controlling which JavaScript symbols are included in Angular's production bundles. The system maintains "golden files" (bundle.golden_symbols.json) that serve as baseline snapshots of all symbols present in compiled bundle outputs. These files enable automated detection of unintended bundle bloat, verify tree-shaking effectiveness, and prevent accidental inclusion of development-only code in production builds.
This page covers the golden symbol file format, symbol categorization, and testing workflows. For information about public API surface management and breaking change detection, see Public API Surface Management.
The following diagram illustrates how source code is transformed into bundles and validated against golden files.
Sources: packages/core/test/bundling/router/bundle.golden_symbols.json1-100 packages/core/test/bundling/defer/bundle.golden_symbols.json1-100
Each bundle test directory contains a bundle.golden_symbols.json file with the following structure:
| Chunk Type | Purpose | Symbol Examples |
|---|---|---|
main | Symbols in the primary application bundle loaded immediately | Core runtime, bootstrap logic, eagerly loaded components |
lazy | Symbols in dynamically loaded chunks | Deferred components, lazy routes, on-demand features |
The separation allows verification that code-splitting is working correctly and that eager bundles don't accidentally include lazy-loaded symbols.
Sources: packages/core/test/bundling/defer/bundle.golden_symbols.json2-58 packages/core/test/bundling/router/bundle.golden_symbols.json2-3
The tracking system monitors various types of code entities, from high-level classes to low-level internal constants.
Sources: packages/core/test/bundling/router/bundle.golden_symbols.json15-135 packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json194-200 packages/core/test/bundling/defer/bundle.golden_symbols.json245-260
These symbols represent the low-level Ivy instructions generated by the Angular compiler:
| Symbol Prefix | Purpose | Generated From | Golden File Examples |
|---|---|---|---|
ɵɵdefine* | Component/directive/pipe definitions | @Component, @Directive, @Pipe decorators | ɵɵdefineComponent, ɵɵdefineDirective, ɵɵdefineInjectable |
ɵɵelement* | DOM element creation/updates | Template element nodes | ɵɵelement, ɵɵelementStart, ɵɵelementEnd |
ɵɵdomElement* | DOM-only element operations | Template nodes without directives | ɵɵdomElementStart, ɵɵdomElementEnd |
ɵɵlistener | Event binding setup | Template (event)="handler()" syntax | ɵɵlistener |
ɵɵproperty | Property binding updates | Template [prop]="value" syntax | ɵɵproperty |
ɵɵtext* | Text node operations | Template text interpolation {{}} | ɵɵtext, ɵɵtextInterpolate |
ɵɵdefer* | Defer block operations | @defer blocks | ɵɵdefer, ɵɵdeferWhen |
ɵɵadvance | Move to next node | Template traversal | ɵɵadvance |
ɵɵinject | Dependency injection | Constructor injection | ɵɵinject, ɵɵdirectiveInject |
Sources: packages/core/test/bundling/defer/bundle.golden_symbols.json245-260 packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json194-199
Core runtime classes and services that manage application lifecycle:
ApplicationRef, ApplicationInitStatus, PlatformRef packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json14-15 packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json205ChangeDetectionScheduler, ChangeDetectionSchedulerImpl, NgZone packages/core/test/bundling/defer/bundle.golden_symbols.json85-86 packages/core/test/bundling/defer/bundle.golden_symbols.json180Injector, R3Injector, EnvironmentInjector, NodeInjector packages/core/test/bundling/defer/bundle.golden_symbols.json145 packages/core/test/bundling/defer/bundle.golden_symbols.json181 packages/core/test/bundling/defer/bundle.golden_symbols.json203ComponentRef, ViewRef, TemplateRef, ViewContainerRef packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json59-60 packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json257AfterRenderManager, EffectScheduler, EffectRefImpl packages/core/test/bundling/defer/bundle.golden_symbols.json66 packages/core/test/bundling/defer/bundle.golden_symbols.json124-125The repository includes multiple test bundles that verify symbol inclusion for different Angular feature combinations.
Sources: packages/core/test/bundling/router/bundle.golden_symbols.json261-264 packages/core/test/bundling/defer/bundle.golden_symbols.json246-247 packages/core/test/bundling/hydration/bundle.golden_symbols.json174-176
| Bundle Type | Main Chunk Symbols Count (Approx) | Purpose |
|---|---|---|
| Standalone Bootstrap | ~250 symbols | Minimal viable Angular app packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json3-250 |
| Router | ~260 symbols (Main) | Full routing capabilities packages/core/test/bundling/router/bundle.golden_symbols.json3-264 |
| Defer Blocks | 57 symbols (Main) | Minimal eager entry point packages/core/test/bundling/defer/bundle.golden_symbols.json3-57 |
| Hydration | ~250 symbols (Main) | SSR with client-side hydration packages/core/test/bundling/hydration/bundle.golden_symbols.json3-250 |
Angular uses specific prefixes to denote internal/private symbols:
| Prefix | Meaning | Visibility | Example |
|---|---|---|---|
ɵɵ | Generated instruction | Public (Internal API) | ɵɵdefineComponent packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json194 |
_ | Private helper | Private | _callAndReportToErrorHandler packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json214 |
__ | Polyfill/shim | Generated | __spreadValues packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json211 |
View-related constants used by the Ivy rendering engine are tracked to ensure they are not renamed or removed accidentally as they define the memory layout of internal structures.
Sources: packages/core/test/bundling/defer/bundle.golden_symbols.json71-73 packages/core/test/bundling/defer/bundle.golden_symbols.json75-76 packages/core/test/bundling/defer/bundle.golden_symbols.json133-134
The validation process is integrated into the Bazel build system.
Every Angular application requires these core bootstrap symbols:
| Symbol | Purpose | File Reference (Approx) |
|---|---|---|
ApplicationRef | Root application reference | packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json15 |
bootstrapApplication | Standalone application startup | packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json257 |
PlatformRef | Platform abstraction layer | packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json205 |
ENVIRONMENT_INITIALIZER | Environment setup hook | packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json66 |
ApplicationInitStatus | Tracks initialization | packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json14 |
Defer blocks demonstrate effective code-splitting by moving most symbols to lazy chunks.
The main bundle for a defer block test contains only a small set of symbols (~57), representing the entry point and platform setup. Sources: packages/core/test/bundling/defer/bundle.golden_symbols.json3-57
The lazy chunk contains the bulk of the framework (~680 symbols), loaded only when the defer block triggers. This includes:
ApplicationRef packages/core/test/bundling/defer/bundle.golden_symbols.json69ChangeDetectionScheduler packages/core/test/bundling/defer/bundle.golden_symbols.json85R3Injector packages/core/test/bundling/defer/bundle.golden_symbols.json203ɵɵdefer packages/core/test/bundling/defer/bundle.golden_symbols.json246The hydration bundle includes specialized symbols for server-side rendering and client rehydration:
NGH_ATTR_NAME packages/core/test/bundling/hydration/bundle.golden_symbols.json174NGH_DATA_KEY packages/core/test/bundling/hydration/bundle.golden_symbols.json175DEHYDRATED_VIEWS packages/core/test/bundling/hydration/bundle.golden_symbols.json76IS_HYDRATION_DOM_REUSE_ENABLED packages/core/test/bundling/hydration/bundle.golden_symbols.json147The animations bundle includes the largest symbol set due to comprehensive animation infrastructure:
AnimationEngine packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json20AnimationDriver packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json19WebAnimationsDriver packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json267TimelineAnimationEngine packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json254Sources: packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json17-32
Refresh this wiki