[web] add --static-assets-url argument to build web (#171638)

micaelcid · web-flow · commit 3be04414e907 · 2025-08-07T17:05:56.000Z
Closes flutter/flutter#171637 As mentioned in the issue, I am proposing a new argument to the flutter build web command: `--static-assets-url`. This argument would accept a full URL string ending with `/` as its value. During the build process, the Flutter tool would use this value to replace a dedicated placeholder within the `web/index.html` file (inspired by `--base-href` approach). Example Implementation: A developer would modify their `web/index.html` to use a new placeholder, for instance, `$FLUTTER_STATIC_ASSETS_URL`: ```html ... <body> <script> {{flutter_js}} {{flutter_build_config}} _flutter.loader.load({ config: { entryPointBaseUrl: "$FLUTTER_STATIC_ASSETS_URL", }, onEntrypointLoaded: async function (engineInitializer) { const appRunner = await engineInitializer.initializeEngine({ assetBase: "$FLUTTER_STATIC_ASSETS_URL", }); await appRunner.runApp(); }, }); </script> </body> ... ``` The build command would be run with the new flag: `flutter build web --static-assets-url="https://static.company.com/some-webapp/“` - and the resulting `build/web/index.html` would have the placeholder replaced: ```html ... <body> <script> {{flutter_js}} {{flutter_build_config}} _flutter.loader.load({ config: { entryPointBaseUrl: "https://static.company.com/some-webapp/", }, onEntrypointLoaded: async function (engineInitializer) { const appRunner = await engineInitializer.initializeEngine({ assetBase: "https://static.company.com/some-webapp/", }); await appRunner.runApp(); }, }); </script> </body> ... ```
diff --git a/packages/flutter_tools/lib/src/build_system/targets/web.dart b/packages/flutter_tools/lib/src/build_system/targets/web.dart
@@ -661,6 +661,7 @@ _flutter.buildConfig = ${jsonEncode(buildConfig)};
 
         final String indexHtmlContent = indexHtmlTemplate.withSubstitutions(
           baseHref: environment.defines[kBaseHref] ?? '/',
+          staticAssetsUrl: environment.defines[kStaticAssetsUrl] ?? '/',
           serviceWorkerVersion: serviceWorkerVersion,
           flutterJsFile: flutterJsFile,
           buildConfig: buildConfig,
diff --git a/packages/flutter_tools/lib/src/commands/build_web.dart b/packages/flutter_tools/lib/src/commands/build_web.dart
@@ -46,6 +46,13 @@ class BuildWebCommand extends BuildSubCommand {
           'The value has to start and end with a slash "/". '
           'For more information: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base',
     );
+    argParser.addOption(
+      'static-assets-url',
+      help:
+          'Used when serving the static assets from a different domain the application is hosted on. '
+          'The value has to end with a slash "/". '
+          'When this is set, it will replace all $kStaticAssetsUrlPlaceholder in web/index.html for the given value.',
+    );
     argParser.addOption(
       'pwa-strategy',
       defaultsTo: ServiceWorkerStrategy.offlineFirst.cliName,
@@ -242,12 +249,19 @@ class BuildWebCommand extends BuildSubCommand {
 
     final BuildInfo buildInfo = await getBuildInfo();
     final String? baseHref = stringArg('base-href');
+    final String? staticAssetsUrl = stringArg('static-assets-url');
     if (baseHref != null && !(baseHref.startsWith('/') && baseHref.endsWith('/'))) {
       throwToolExit(
         'Received a --base-href value of "$baseHref"\n'
         '--base-href should start and end with /',
       );
     }
+    if (staticAssetsUrl != null && !staticAssetsUrl.endsWith('/')) {
+      throwToolExit(
+        'Received a --static-assets-url value of "$staticAssetsUrl"\n'
+        '--static-assets-url should end with /',
+      );
+    }
     if (!project.web.existsSync()) {
       throwToolExit(
         'This project is not configured for the web.\n'
@@ -285,6 +299,7 @@ class BuildWebCommand extends BuildSubCommand {
       ServiceWorkerStrategy.fromCliName(stringArg('pwa-strategy')),
       compilerConfigs: compilerConfigs,
       baseHref: baseHref,
+      staticAssetsUrl: staticAssetsUrl,
       outputDirectoryPath: outputDirectoryPath,
     );
     return FlutterCommandResult.success();
diff --git a/packages/flutter_tools/lib/src/isolated/web_asset_server.dart b/packages/flutter_tools/lib/src/isolated/web_asset_server.dart
@@ -648,6 +648,8 @@ _flutter.buildConfig = ${jsonEncode(buildConfig)};
       indexHtml.withSubstitutions(
         // Currently, we don't support --base-href for the "run" command.
         baseHref: '/',
+        // Currently, we don't support --static-assets-url for the "run" command.
+        staticAssetsUrl: '/',
         serviceWorkerVersion: null,
         buildConfig: _buildConfigString,
         flutterJsFile: _flutterJsFile,
diff --git a/packages/flutter_tools/lib/src/web/compile.dart b/packages/flutter_tools/lib/src/web/compile.dart
@@ -32,6 +32,9 @@ const kHasWebPlugins = 'HasWebPlugins';
 /// Base href to set in index.html in flutter build command
 const kBaseHref = 'baseHref';
 
+/// Static assets url to set in index.html in flutter build command
+const kStaticAssetsUrl = 'staticAssetsUrl';
+
 /// The caching strategy to use for service worker generation.
 const kServiceWorkerStrategy = 'ServiceWorkerStrategy';
 
@@ -64,6 +67,7 @@ class WebBuilder {
     ServiceWorkerStrategy serviceWorkerStrategy, {
     required List<WebCompilerConfig> compilerConfigs,
     String? baseHref,
+    String? staticAssetsUrl,
     String? outputDirectoryPath,
   }) async {
     final bool hasWebPlugins = (await findPlugins(
@@ -99,6 +103,7 @@ class WebBuilder {
             kTargetFile: target,
             kHasWebPlugins: hasWebPlugins.toString(),
             if (baseHref != null) kBaseHref: baseHref,
+            if (staticAssetsUrl != null) kStaticAssetsUrl: staticAssetsUrl,
             kServiceWorkerStrategy: serviceWorkerStrategy.cliName,
             ...buildInfo.toBuildSystemEnvironment(),
           },
diff --git a/packages/flutter_tools/lib/src/web_template.dart b/packages/flutter_tools/lib/src/web_template.dart
@@ -11,6 +11,7 @@ import 'base/file_system.dart';
 
 /// Placeholder for base href
 const kBaseHrefPlaceholder = r'$FLUTTER_BASE_HREF';
+const kStaticAssetsUrlPlaceholder = r'$FLUTTER_STATIC_ASSETS_URL';
 
 class WebTemplateWarning {
   WebTemplateWarning(this.warningText, this.lineNumber);
@@ -101,13 +102,18 @@ class WebTemplate {
     required File flutterJsFile,
     String? buildConfig,
     String? flutterBootstrapJs,
+    String? staticAssetsUrl,
   }) {
     String newContent = _content;
 
     if (newContent.contains(kBaseHrefPlaceholder)) {
       newContent = newContent.replaceAll(kBaseHrefPlaceholder, baseHref);
     }
 
+    if (newContent.contains(kStaticAssetsUrlPlaceholder) && staticAssetsUrl != null) {
+      newContent = newContent.replaceAll(kStaticAssetsUrlPlaceholder, staticAssetsUrl);
+    }
+
     if (serviceWorkerVersion != null) {
       newContent = newContent
           .replaceFirst(
diff --git a/packages/flutter_tools/test/commands.shard/hermetic/build_web_test.dart b/packages/flutter_tools/test/commands.shard/hermetic/build_web_test.dart
@@ -654,6 +654,33 @@ void main() {
     },
   );
 
+  testUsingContext(
+    'Rejects --static-assets-url value that does not end with /',
+    () async {
+      final buildCommand = TestWebBuildCommand(fileSystem: fileSystem);
+      final CommandRunner<void> runner = createTestCommandRunner(buildCommand);
+
+      await expectLater(
+        runner.run(<String>[
+          'build',
+          'web',
+          '--no-pub',
+          '--static-assets-url=i_dont_end_with_forward_slash',
+        ]),
+        throwsToolExit(
+          message:
+              'Received a --static-assets-url value of "i_dont_end_with_forward_slash"\n'
+              '--static-assets-url should end with /',
+        ),
+      );
+    },
+    overrides: <Type, Generator>{
+      Platform: () => fakePlatform,
+      FileSystem: () => fileSystem,
+      ProcessManager: () => processManager,
+    },
+  );
+
   testUsingContext(
     'flutter build web option visibility',
     () async {
diff --git a/packages/flutter_tools/test/general.shard/build_system/targets/web_test.dart b/packages/flutter_tools/test/general.shard/build_system/targets/web_test.dart
@@ -254,6 +254,45 @@ name: foo
     }),
   );
 
+  group('--static-assets-url', () {
+    test(
+      'WebTemplatedFiles replaces placeholder with given value',
+      () => testbed.run(() async {
+        environment.defines[kStaticAssetsUrl] = 'https://static.example.com/example-app/';
+        final Directory webResources = environment.projectDir.childDirectory('web');
+        webResources.childFile('index.html').createSync(recursive: true);
+        webResources.childFile('index.html').writeAsStringSync('''
+<!DOCTYPE html><html><body><script>const staticAssetsUrl = "$kStaticAssetsUrlPlaceholder";</script></body></html>
+    ''');
+        environment.buildDir.childFile('main.dart.js').createSync();
+        await WebTemplatedFiles(<Map<String, Object?>>[]).build(environment);
+
+        expect(
+          environment.outputDir.childFile('index.html').readAsStringSync(),
+          contains('https://static.example.com/example-app/'),
+        );
+      }),
+    );
+
+    test(
+      'WebTemplatedFiles replaces placeholder with / when not set',
+      () => testbed.run(() async {
+        final Directory webResources = environment.projectDir.childDirectory('web');
+        webResources.childFile('index.html').createSync(recursive: true);
+        webResources.childFile('index.html').writeAsStringSync('''
+<!DOCTYPE html><html><body><script>const staticAssetsUrl = "$kStaticAssetsUrlPlaceholder";</script></body></html>
+    ''');
+        environment.buildDir.childFile('main.dart.js').createSync();
+        await WebTemplatedFiles(<Map<String, Object?>>[]).build(environment);
+
+        expect(
+          environment.outputDir.childFile('index.html').readAsStringSync(),
+          contains('staticAssetsUrl = "/"'),
+        );
+      }),
+    );
+  });
+
   test(
     'WebReleaseBundle copies dart2js output and resource files to output directory',
     () => testbed.run(() async {
diff --git a/packages/flutter_tools/test/general.shard/web_template_test.dart b/packages/flutter_tools/test/general.shard/web_template_test.dart
@@ -219,6 +219,70 @@ const htmlSample3 = '''
 </html>
 ''';
 
+const htmlSampleStaticAssetsUrl =
+    '''
+<!DOCTYPE html>
+<html>
+<head>
+  <title></title>
+  <base href="/">
+  <meta charset="utf-8">
+  <link rel="icon" type="image/png" href="favicon.png"/>
+</head>
+<body>
+  <div></div>
+  <script>
+    {{flutter_js}}
+    {{flutter_build_config}}
+    _flutter.loader.load({
+      config: {
+        entryPointBaseUrl: "$kStaticAssetsUrlPlaceholder",
+      },
+      onEntrypointLoaded: async function (engineInitializer) {
+        const appRunner = await engineInitializer.initializeEngine({
+          assetBase: "$kStaticAssetsUrlPlaceholder",
+        });
+
+        await appRunner.runApp();
+      },
+    });
+  </script>
+</body>
+</html>
+''';
+
+String htmlSampleStaticAssetsUrlReplaced({required String staticAssetsUrl}) =>
+    '''
+<!DOCTYPE html>
+<html>
+<head>
+  <title></title>
+  <base href="/">
+  <meta charset="utf-8">
+  <link rel="icon" type="image/png" href="favicon.png"/>
+</head>
+<body>
+  <div></div>
+  <script>
+    (flutter.js content)
+    {{flutter_build_config}}
+    _flutter.loader.load({
+      config: {
+        entryPointBaseUrl: "$staticAssetsUrl",
+      },
+      onEntrypointLoaded: async function (engineInitializer) {
+        const appRunner = await engineInitializer.initializeEngine({
+          assetBase: "$staticAssetsUrl",
+        });
+
+        await appRunner.runApp();
+      },
+    });
+  </script>
+</body>
+</html>
+''';
+
 void main() {
   final fs = MemoryFileSystem();
   final File flutterJs = fs.file('flutter.js');
@@ -300,6 +364,21 @@ void main() {
     );
   });
 
+  test('applies substitutions to static assets url', () {
+    const indexHtml = WebTemplate(htmlSampleStaticAssetsUrl);
+    const expectedStaticAssetsUrl = 'https://static.example.com/my-app/';
+
+    expect(
+      indexHtml.withSubstitutions(
+        baseHref: '/',
+        serviceWorkerVersion: 'v123xyz',
+        flutterJsFile: flutterJs,
+        staticAssetsUrl: expectedStaticAssetsUrl,
+      ),
+      htmlSampleStaticAssetsUrlReplaced(staticAssetsUrl: expectedStaticAssetsUrl),
+    );
+  });
+
   test('re-parses after substitutions', () {
     const indexHtml = WebTemplate(htmlSample2);
     expect(WebTemplate.baseHref(htmlSample2), ''); // Placeholder base href.
