feat(router): add trailingSlash config option

This commit introduces a highly requested `trailingSlash` configuration option to the Angular Router, allowing developers to control how trailing slashes are handled in their applications. The options are:
- 'always': Enforces a trailing slash on all URLs.
- 'never': Removes trailing slashes from all URLs (default).
- 'preserve': Respects the presence or absence of a trailing slash as defined in the UrlTree.

Author: atscott

adev/src/content/guide/routing/customizing-route-behavior.md

@@ -127,6 +127,20 @@ provideRouter(routes, withRouterConfig({defaultQueryParamsHandling: 'merge'}));
 
 This is especially helpful for search and filter pages to automatically retain existing filters when additional parameters are provided.
 
+### Configure trailing slash handling
+
+`trailingSlash` configures how the router and location service handle trailing slashes in URLs.
+
+- `'always'`: Forces a trailing slash on all URLs.
+- `'never'`: Removes trailing slashes from all URLs.
+- `'preserve'`: Keeps the trailing slash if present, and omits it if not.
+
+NOTE: By default, the `DefaultUrlSerializer` preserves trailing slashes, but `Location.path()` and `Location.normalize()` strip them.
+
+```ts
+provideRouter(routes, withRouterConfig({trailingSlash: 'preserve'}));
+```
+
 Angular Router exposes four main areas for customization:
 
   <docs-pill-row>
@@ -224,7 +238,7 @@ When implementing a custom `RouteReuseStrategy`, you may need to manually destro
 Since `DetachedRouteHandle` is an opaque type, you cannot call a destroy method directly on it. Instead, use the `destroyDetachedRouteHandle` function provided by the Router.
 
 ```ts
-import { destroyDetachedRouteHandle } from '@angular/router';
+import {destroyDetachedRouteHandle} from '@angular/router';
 
 // ... inside your strategy
 if (this.handles.size > MAX_CACHE_SIZE) {
@@ -245,12 +259,10 @@ By default, Angular does not destroy the injectors of detached routes, even if t
 To enable automatic cleanup of unused route injectors, you can use the `withExperimentalAutoCleanupInjectors` feature in your router configuration. This feature checks which routes are currently stored by the strategy after navigations and destroys the injectors of any detached routes that are not currently stored by the reuse strategy.
 
 ```ts
-import { provideRouter, withExperimentalAutoCleanupInjectors } from '@angular/router';
+import {provideRouter, withExperimentalAutoCleanupInjectors} from '@angular/router';
 
 export const appConfig: ApplicationConfig = {
-  providers: [
-    provideRouter(routes, withExperimentalAutoCleanupInjectors())
-  ]
+  providers: [provideRouter(routes, withExperimentalAutoCleanupInjectors())],
 };
 ```
 

goldens/public-api/common/index.api.md

@@ -948,6 +948,9 @@ export function provideNetlifyLoader(path?: string): Provider[];
 // @public
 export function registerLocaleData(data: any, localeId?: string | any, extraData?: any): void;
 
+// @public
+export const REMOVE_TRAILING_SLASH: InjectionToken<boolean>;
+
 // @public
 export class SlicePipe implements PipeTransform {
     // (undocumented)

goldens/public-api/router/index.api.md

@@ -238,6 +238,7 @@ export function defaultUrlMatcher(segments: UrlSegment[], segmentGroup: UrlSegme
 
 // @public
 export class DefaultUrlSerializer implements UrlSerializer {
+    constructor();
     parse(url: string): UrlTree;
     serialize(tree: UrlTree): string;
 }
@@ -764,6 +765,7 @@ export interface RouterConfigOptions {
     onSameUrlNavigation?: OnSameUrlNavigation;
     paramsInheritanceStrategy?: 'emptyOnly' | 'always';
     resolveNavigationPromiseOnError?: boolean;
+    trailingSlash?: 'always' | 'never' | 'preserve';
     urlUpdateStrategy?: 'deferred' | 'eager';
 }
 

packages/common/src/location/index.ts

@@ -7,7 +7,7 @@
  */
 
 export {HashLocationStrategy} from './hash_location_strategy';
-export {Location, PopStateEvent} from './location';
+export {Location, PopStateEvent, REMOVE_TRAILING_SLASH} from './location';
 export {APP_BASE_HREF, LocationStrategy, PathLocationStrategy} from './location_strategy';
 export {
   BrowserPlatformLocation,

packages/common/src/location/location.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Injectable, OnDestroy, ɵɵinject} from '@angular/core';
+import {Injectable, InjectionToken, OnDestroy, inject, ɵɵinject} from '@angular/core';
 import {Subject, SubscriptionLike} from 'rxjs';
 
 import {LocationStrategy} from './location_strategy';
@@ -20,6 +20,22 @@ export interface PopStateEvent {
   url?: string;
 }
 
+/**
+ * A token that can be provided to configure whether the `Location` service should
+ * strip trailing slashes from URLs.
+ *
+ * If `true`, the `Location` service will remove trailing slashes from URLs.
+ * If `false`, the `Location` service will not remove trailing slashes from URLs.
+ *
+ * @publicApi
+ */
+export const REMOVE_TRAILING_SLASH = new InjectionToken<boolean>(
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'remove trailing slash' : '',
+  {
+    factory: () => true,
+  },
+);
+
 /**
  * @description
  *
@@ -35,23 +51,22 @@ export interface PopStateEvent {
  * routing.
  *
  * `Location` is responsible for normalizing the URL against the application's base href.
- * A normalized URL is absolute from the URL host, includes the application's base href, and has no
- * trailing slash:
+ * A normalized URL is absolute from the URL host, includes the application's base href, and may
+ * have a trailing slash:
  * - `/my/app/user/123` is normalized
  * - `my/app/user/123` **is not** normalized
- * - `/my/app/user/123/` **is not** normalized
+ * - `/my/app/user/123/` **is** normalized if `REMOVE_TRAILING_SLASH` is `false`
  *
  * ### Example
  *
  * {@example common/location/ts/path_location_component.ts region='LocationComponent'}
  *
+ * @see {@link LocationStrategy}
+ * @see [Routing and Navigation Guide](guide/routing/common-router-tasks)
+ *
  * @publicApi
  */
-@Injectable({
-  providedIn: 'root',
-  // See #23917
-  useFactory: createLocation,
-})
+@Injectable({providedIn: 'root', useFactory: createLocation})
 export class Location implements OnDestroy {
   /** @internal */
   _subject = new Subject<PopStateEvent>();
@@ -63,9 +78,17 @@ export class Location implements OnDestroy {
   _urlChangeListeners: ((url: string, state: unknown) => void)[] = [];
   /** @internal */
   _urlChangeSubscription: SubscriptionLike | null = null;
+  /** @internal */
+  readonly _stripTrailingSlash: boolean;
 
   constructor(locationStrategy: LocationStrategy) {
     this._locationStrategy = locationStrategy;
+    try {
+      this._stripTrailingSlash = inject(REMOVE_TRAILING_SLASH, {optional: true}) ?? true;
+    } catch {
+      // failsafe against not calling constructor in injection context
+      this._stripTrailingSlash = true;
+    }
     const baseHref = this._locationStrategy.getBaseHref();
     // Note: This class's interaction with base HREF does not fully follow the rules
     // outlined in the spec https://www.freesoft.org/CIE/RFC/1808/18.htm.
@@ -132,7 +155,8 @@ export class Location implements OnDestroy {
    * @returns The normalized URL string.
    */
   normalize(url: string): string {
-    return Location.stripTrailingSlash(_stripBasePath(this._basePath, _stripIndexHtml(url)));
+    const s = _stripBasePath(this._basePath, _stripIndexHtml(url));
+    return this._stripTrailingSlash ? Location.stripTrailingSlash(s) : s;
   }
 
   /**

packages/common/test/location/location_spec.ts

@@ -13,6 +13,7 @@ import {
   LocationStrategy,
   PathLocationStrategy,
   PlatformLocation,
+  REMOVE_TRAILING_SLASH,
 } from '../../index';
 import {MockLocationStrategy, MockPlatformLocation} from '../../testing';
 import {TestBed} from '@angular/core/testing';
@@ -305,4 +306,18 @@ describe('Location Class', () => {
       expect(location.normalize(baseHref + path)).toBe(path);
     });
   });
+  describe('Location with REMOVE_TRAILING_SLASH', () => {
+    it('should strip trailing slash by default', () => {
+      const location = TestBed.inject(Location);
+      expect(location.normalize('/a/b/')).toBe('/a/b');
+    });
+
+    it('should NOT strip trailing slash when REMOVE_TRAILING_SLASH is false', () => {
+      TestBed.configureTestingModule({
+        providers: [{provide: REMOVE_TRAILING_SLASH, useValue: false}],
+      });
+      const location = TestBed.inject(Location);
+      expect(location.normalize('/a/b/')).toBe('/a/b/');
+    });
+  });
 });

packages/common/testing/src/location_mock.ts

@@ -35,6 +35,8 @@ export class SpyLocation implements Location {
   _urlChangeListeners: ((url: string, state: unknown) => void)[] = [];
   /** @internal */
   _urlChangeSubscription: SubscriptionLike | null = null;
+  /** @internal */
+  _stripTrailingSlash = true;
 
   /** @docs-private */
   ngOnDestroy(): void {

packages/core/test/bundling/router/bundle.golden_symbols.json

@@ -236,6 +236,7 @@
       "REACTIVE_TEMPLATE_CONSUMER",
       "REMOVE_STYLES_ON_COMPONENT_DESTROY",
       "REMOVE_STYLES_ON_COMPONENT_DESTROY_DEFAULT",
+      "REMOVE_TRAILING_SLASH",
       "RENDERER",
       "REQUIRED_UNSET_VALUE",
       "ROUTER_CONFIGURATION",

packages/router/src/provide_router.ts

@@ -12,6 +12,7 @@ import {
   LocationStrategy,
   ViewportScroller,
   Location,
+  REMOVE_TRAILING_SLASH,
   ɵNavigationAdapterForLocation,
 } from '@angular/common';
 import {
@@ -675,7 +676,16 @@ export type RouterConfigurationFeature =
  * @publicApi
  */
 export function withRouterConfig(options: RouterConfigOptions): RouterConfigurationFeature {
-  const providers = [{provide: ROUTER_CONFIGURATION, useValue: options}];
+  const providers = [
+    {provide: ROUTER_CONFIGURATION, useValue: options},
+    {
+      provide: REMOVE_TRAILING_SLASH,
+      useFactory: () => {
+        const {trailingSlash} = options;
+        return trailingSlash === 'always' || trailingSlash === 'preserve' ? false : true;
+      },
+    },
+  ];
   return routerFeature(RouterFeatureKind.RouterConfigurationFeature, providers);
 }
 

packages/router/src/router_config.ts

@@ -110,6 +110,18 @@ export interface RouterConfigOptions {
    */
   urlUpdateStrategy?: 'deferred' | 'eager';
 
+  /**
+   * Configures how the `DefaultUrlSerializer` and `Location` service handle trailing slashes in URLs.
+   *
+   * - 'always': Forces a trailing slash on all URLs.
+   * - 'never': Removes trailing slashes from all URLs.
+   * - 'preserve': Keeps the trailing slash if present, and omits it if not.
+   *
+   * Note: By default, the `DefaultUrlSerializer` preserves trailing slashes, but `Location.path()`
+   * and `Location.normalize()` strip them.
+   */
+  trailingSlash?: 'always' | 'never' | 'preserve';
+
   /**
    * The default strategy to use for handling query params in `Router.createUrlTree` when one is not provided.
    *