@angular/router

Client-side routing: URL ↔ component-tree mapping, navigation lifecycle events, route guards, route data, and lazy/standalone route configuration.

Purpose

The router is responsible for:

• Matching the current URL against a Routes array and building the resulting ActivatedRouteSnapshot tree.
• Performing navigation: running guards, resolvers, lazy-loading any matched routes, then activating the new component tree in the matching RouterOutlets.
• Emitting an Observable<Event> on Router.events so apps can observe and react to the navigation lifecycle (NavigationStart, RoutesRecognized, GuardsCheckStart, NavigationEnd, etc.).
• Parsing and serializing URLs through UrlTree/UrlSerializer.
• Generating links via the routerLink directive and the Router.createUrlTree API.

Directory layout

packages/router/
├── src/
│   ├── router.ts               # The Router service
│   ├── router_module.ts        # RouterModule (legacy NgModule API)
│   ├── provide_router.ts       # provideRouter standalone API
│   ├── router_outlet.ts        # <router-outlet>
│   ├── directives/             # routerLink, routerLinkActive
│   ├── url_tree.ts             # UrlTree, UrlSegment
│   ├── shared.ts               # PRIMARY_OUTLET, etc.
│   ├── route_reuse_strategy.ts # RouteReuseStrategy
│   ├── recognize.ts            # URL → ActivatedRouteSnapshot tree
│   ├── apply_redirects.ts      # Redirects evaluation
│   ├── operators/              # RxJS operators used by navigation
│   ├── events.ts               # Navigation event types
│   ├── router_state.ts         # ActivatedRoute / Snapshot
│   ├── router_preloader.ts     # PreloadAllModules + custom strategies
│   ├── transfer_state.ts       # SSR-side state transfer hooks
│   └── ...
├── upgrade/                    # Hybrid Angular.js routing helpers
├── testing/                    # RouterTestingHarness
└── schematics/migrations/      # provideRouter, withRouterConfig migrations

Key abstractions

Type / function	File	What it is
Router	packages/router/src/router.ts	The service that drives navigation.
provideRouter	packages/router/src/provide_router.ts	The standalone-bootstrap registration entry. Replaces RouterModule.forRoot.
RouterOutlet	packages/router/src/router_outlet.ts	The placeholder where matched components render.
Routes	packages/router/src/models.ts	Array type describing a route configuration.
ActivatedRoute, ActivatedRouteSnapshot	packages/router/src/router_state.ts	Per-route info available to components and guards.
routerLink	packages/router/src/directives/router_link.ts	The link directive.
RouterStateSnapshot	router_state.ts	The whole router-state tree at a moment in time.
UrlTree / UrlSegment / UrlSerializer	packages/router/src/url_tree.ts, url_handling_strategy.ts	URL parsing and serialization.
PreloadingStrategy, PreloadAllModules	packages/router/src/router_preloader.ts	Lazy-route preloaders.

Navigation pipeline

graph TD
  Trigger["Navigation trigger<br/>(routerLink, navigate(), popstate)"] --> Recognize["recognize()<br/>URL → snapshot tree"]
  Recognize --> Redirects["applyRedirects()"]
  Redirects --> Lazy["Load lazy chunks<br/>(loadChildren, loadComponent)"]
  Lazy --> Guards["CanActivate / CanLoad / CanMatch"]
  Guards --> Resolvers["Resolve data"]
  Resolvers --> Activate["Activate components<br/>(swap in RouterOutlets)"]
  Activate --> Events["Emit NavigationEnd"]

Each stage emits matching Events on Router.events. The pipeline is implemented as a sequence of RxJS operators in packages/router/src/operators/, composed in Router.scheduleNavigation.

Standalone vs NgModule

The standalone API (provideRouter) is the recommended entry point:

bootstrapApplication(AppRoot, {
  providers: [
    provideRouter(routes, withComponentInputBinding(), withInMemoryScrolling()),
  ],
});

provideRouter accepts feature functions (withDebugTracing, withRouterConfig, withInMemoryScrolling, withHashLocation, withPreloading, etc.) defined in provide_router.ts.

RouterModule.forRoot(routes, options) is still supported for legacy code; an ng update-driven migration converts most call sites automatically.

Integration points

• @angular/common — depends on Location and LocationStrategy for URL manipulation.
• @angular/platform-browser — registers the browser-specific LocationStrategy.
• @angular/platform-server — feeds the initial URL into the router during SSR via INITIAL_CONFIG.
• Component input binding — withComponentInputBinding() exposes route params/data as @Input() properties on routed components, removing most direct ActivatedRoute injection.
• Component-level signal queries — withComponentInputBinding() is signal-aware; signal-based inputs receive route values automatically.

Migrations

packages/router/schematics/ contains migrations to:

• Convert RouterModule.forRoot(...) to provideRouter(...).
• Replace router-related import paths after refactors.
• Adopt new feature functions like withRouterConfig.

Entry points for modification

• A new feature function for provideRouter: define a withFoo() function in provide_router.ts, backed by an EnvironmentProviders array. The naming and shape are enforced by review.
• A new navigation event: extend Event in events.ts, emit it from the matching pipeline operator, and document it in the JSDoc.
• A new directive (similar to routerLink): add it under directives/ and export from public_api.ts.

For testing, prefer RouterTestingHarness from packages/router/testing over manual RouterTestingModule setup. The harness handles the zoneless waiting pattern correctly.