feat(serve): Add --spa-fallback flag for SPA routing

When developing Single Page Applications (SPAs) that use client-side routing with the HTML5 History API (e.g., Angular's PathLocationStrategy), refreshing the page on a deep link results in a 404 error because the server can't find a corresponding file for the route. This change introduces a --spa-fallback flag to the webdev serve command. When enabled, the development server will serve the root index.html file for any GET request that would otherwise result in a 404, as long as the path does not appear to be a direct file asset (i.e., does not contain a file extension). This allows the client-side router to take over and handle the request, enabling a seamless development workflow for modern web applications.

Author: insinfo

webdev/lib/src/command/configuration.dart

@@ -38,6 +38,7 @@ const disableDdsFlag = 'disable-dds';
 const enableExperimentOption = 'enable-experiment';
 const canaryFeaturesFlag = 'canary';
 const offlineFlag = 'offline';
+const spaFallbackFlag = 'spa-fallback';
 
 ReloadConfiguration _parseReloadConfiguration(ArgResults argResults) {
   var auto = argResults.options.contains(autoOption)
@@ -109,6 +110,7 @@ class Configuration {
   final List<String>? _experiments;
   final bool? _canaryFeatures;
   final bool? _offline;
+  final bool? _spaFallback;
 
   Configuration({
     bool? autoRun,
@@ -136,6 +138,7 @@ class Configuration {
     List<String>? experiments,
     bool? canaryFeatures,
     bool? offline,
+    bool? spaFallback,
   })  : _autoRun = autoRun,
         _chromeDebugPort = chromeDebugPort,
         _debugExtension = debugExtension,
@@ -158,7 +161,8 @@ class Configuration {
         _nullSafety = nullSafety,
         _experiments = experiments,
         _canaryFeatures = canaryFeatures,
-        _offline = offline {
+        _offline = offline,
+        _spaFallback = spaFallback {
     _validateConfiguration();
   }
 
@@ -234,7 +238,8 @@ class Configuration {
       nullSafety: other._nullSafety ?? _nullSafety,
       experiments: other._experiments ?? _experiments,
       canaryFeatures: other._canaryFeatures ?? _canaryFeatures,
-      offline: other._offline ?? _offline);
+      offline: other._offline ?? _offline,
+      spaFallback: other._spaFallback ?? _spaFallback);
 
   factory Configuration.noInjectedClientDefaults() =>
       Configuration(autoRun: false, debug: false, debugExtension: false);
@@ -291,6 +296,8 @@ class Configuration {
 
   bool get offline => _offline ?? false;
 
+  bool get spaFallback => _spaFallback ?? false;
+
   /// Returns a new configuration with values updated from the parsed args.
   static Configuration fromArgs(ArgResults? argResults,
       {Configuration? defaultConfiguration}) {
@@ -419,6 +426,10 @@ class Configuration {
         ? argResults[offlineFlag] as bool?
         : defaultConfiguration.verbose;
 
+    final spaFallback = argResults.options.contains(spaFallbackFlag)
+        ? argResults[spaFallbackFlag] as bool?
+        : defaultConfiguration.spaFallback;
+
     return Configuration(
       autoRun: defaultConfiguration.autoRun,
       chromeDebugPort: chromeDebugPort,
@@ -445,6 +456,7 @@ class Configuration {
       experiments: experiments,
       canaryFeatures: canaryFeatures,
       offline: offline,
+      spaFallback: spaFallback,
     );
   }
 }

webdev/lib/src/command/serve_command.dart

@@ -75,6 +75,10 @@ refresh: Performs a full page refresh.
     ..addFlag(logRequestsFlag,
         negatable: false,
         help: 'Enables logging for each request to the server.')
+    ..addFlag('spa-fallback',
+        negatable: false,
+        help: 'Serves index.html for any 404 from a non-asset request. '
+            'Useful for single-page applications with client-side routing.')
     ..addOption(tlsCertChainFlag,
         help:
             'The file location to a TLS Certificate to create an HTTPs server.\n'

webdev/lib/src/serve/webdev_server.dart

@@ -195,6 +195,25 @@ class WebDevServer {
       cascade = cascade.add(assetHandler);
     }
 
+    if (options.configuration.spaFallback) {
+      FutureOr<Response> spaFallbackHandler(Request request) async {
+        final uri = request.requestedUri;
+        final hasExtension =
+            uri.pathSegments.isNotEmpty && uri.pathSegments.last.contains('.');
+        if (request.method != 'GET' || hasExtension) {
+          return Response.notFound('Not Found');
+        }
+        final indexResponse =
+            await assetHandler(request.change(path: 'index.html'));
+
+        return indexResponse.statusCode == 200
+            ? indexResponse
+            : Response.notFound('Not Found');
+      }
+
+      cascade = cascade.add(spaFallbackHandler);
+    }
+
     final hostname = options.configuration.hostname;
     final tlsCertChain = options.configuration.tlsCertChain ?? '';
     final tlsCertKey = options.configuration.tlsCertKey ?? '';