From 49d83f489236073212ce4c7ba8c6c19ec1a1037b Mon Sep 17 00:00:00 2001
From: Simon Binder <oss@simonbinder.eu>
Date: Wed, 11 Sep 2024 00:02:32 +0200
Subject: [PATCH] Compile with dart2js and dart2wasm (#3737)

---
 _test/build.both.yaml                         |  23 ++
 _test/test/dart2wasm_integration_test.dart    |  23 ++
 build_web_compilers/CHANGELOG.md              |   6 +-
 build_web_compilers/README.md                 | 202 +++++++--
 .../lib/src/dart2js_bootstrap.dart            |  16 +-
 .../lib/src/dart2wasm_bootstrap.dart          |  49 +--
 .../lib/src/dev_compiler_bootstrap.dart       |   3 +-
 .../lib/src/web_entrypoint_builder.dart       | 388 ++++++++++++++----
 build_web_compilers/pubspec.yaml              |   2 +-
 .../test/dart2js_bootstrap_test.dart          |  20 +-
 .../test/dart2wasm_bootstrap_test.dart        | 103 +++++
 .../test/dev_compiler_bootstrap_test.dart     |  18 +-
 .../test/entrypoint_options_test.dart         |  97 +++++
 13 files changed, 786 insertions(+), 164 deletions(-)
 create mode 100644 _test/build.both.yaml
 create mode 100644 build_web_compilers/test/dart2wasm_bootstrap_test.dart
 create mode 100644 build_web_compilers/test/entrypoint_options_test.dart

diff --git a/_test/build.both.yaml b/_test/build.both.yaml
new file mode 100644
index 000000000..2a1800020
--- /dev/null
+++ b/_test/build.both.yaml
@@ -0,0 +1,23 @@
+targets:
+  $default:
+    builders:
+      build_web_compilers:entrypoint:
+        options:
+          compilers:
+            dart2wasm:
+            dart2js:
+          loader: .dart.js
+        generate_for:
+          - web/main.dart
+          - web/sub/main.dart
+          - test/configurable_uri_test.dart
+          - test/configurable_uri_test.dart.browser_test.dart
+          - test/hello_world_test.dart
+          - test/hello_world_test.dart.browser_test.dart
+          - test/hello_world_deferred_test.dart
+          - test/hello_world_deferred_test.dart.browser_test.dart
+          - test/hello_world_custom_html_test.dart
+          - test/hello_world_custom_html_test.dart.browser_test.dart
+          - test/other_test.dart.browser_test.dart
+          - test/sub-dir/subdir_test.dart
+          - test/sub-dir/subdir_test.dart.browser_test.dart
diff --git a/_test/test/dart2wasm_integration_test.dart b/_test/test/dart2wasm_integration_test.dart
index 6a1acd093..7a7777978 100644
--- a/_test/test/dart2wasm_integration_test.dart
+++ b/_test/test/dart2wasm_integration_test.dart
@@ -59,6 +59,29 @@ void main() {
       );
       await _expectWasCompiledWithDart2Wasm();
     }, onPlatform: {'windows': const Skip('flaky on windows')});
+
+    test('when also enabling dart2js', () async {
+      await expectTestsPass(
+        usePrecompiled: true,
+        buildArgs: [
+          '--release',
+          '--config=both',
+          '--output=${d.sandbox}',
+        ],
+        testArgs: _testArgs,
+      );
+      await _expectWasCompiledWithDart2Wasm();
+
+      await d.dir(
+        'test',
+        [
+          d.file(
+            'hello_world_deferred_test.dart.browser_test.dart2js.js',
+            startsWith('// Generated by dart2js'),
+          ),
+        ],
+      ).validate();
+    }, onPlatform: {'windows': const Skip('flaky on windows')});
   });
 }
 
diff --git a/build_web_compilers/CHANGELOG.md b/build_web_compilers/CHANGELOG.md
index 94184e358..8430acc28 100644
--- a/build_web_compilers/CHANGELOG.md
+++ b/build_web_compilers/CHANGELOG.md
@@ -1,8 +1,10 @@
-## 4.0.12-wip
+## 4.1.0-wip
 
-- Account for dartdevc snapshot in the Dart SDK changing to an AOT snapshot.
 - Support compiling to WebAssembly by using `dart2wasm` as a value for the
   compiler option.
+- Support compiling with multiple compilers (e.g. `dart2js` and `dart2wasm`)
+  with a new `compilers` option.
+- Account for dartdevc snapshot in the Dart SDK changing to an AOT snapshot.
 - Bump the min sdk to 3.6.0-165.0.dev.
 
 ## 4.0.11
diff --git a/build_web_compilers/README.md b/build_web_compilers/README.md
index 1606e7d1f..d03d6ab24 100644
--- a/build_web_compilers/README.md
+++ b/build_web_compilers/README.md
@@ -39,14 +39,35 @@ then all you need is the `dev_dependency` listed above.
 
 ## Configuration
 
-### Configuring the default compiler
-
 By default, this package uses the [Dart development compiler][] (_dartdevc_,
 also known as _DDC_) to compile Dart to JavaScript. In release builds (running
-the build tool with `--release`, the default compiler is `dart2js`).
+the build tool with `--release`), `dart2js` is used as a compiler.
+
+In addition to compiling to JavaScript, this package also supports compiling to
+WebAssembly. Currently, `dart2wasm` needs to be enabled with builder options.
+To understand the impact of these options, be aware of differences between
+compiling to JavaScript and compiling to WebAssembly:
+
+1. Dart has two compilers emitting JavaScript: `dart2js` and `dartdevc` (which
+  supports incremental rebuilds but is typically only used for development).
+  For both JavaScript compilers, `build_web_compilers` generates a primary
+  entrypoint script and additional module files or source maps depending on
+  compiler options.
+2. Compiling with `dart2wasm` generates a WebAssembly module (a `.wasm` file)
+   and a JavaScript module (a `.mjs` file) exporting functions to instantiate
+   that module. `dart2wasm` alone generates no entrypoint file that could be
+   added as a `<script>` tag.
+
+In addition to invoking compilers, `build_web_compilers` can emit an entrypoint
+file suitable for `dart2wasm`. When both `dart2wasm` and a JavaScript compiler
+are enabled, the entrypoint file runs a feature detection for WasmGC and loads
+either the WebAssembly module or the JavaScript file depending on what the
+browser supports.
+
+### Compiler arguments
 
-If you would like to opt into dart2js for all builds, you will need to add a
-`build.yaml` file, which should look roughly like the following:
+To customize compilers, you will need to add a `build.yaml` file configuring
+the `build_web_compilers:entrypoint` builder, similar to the following:
 
 ```yaml
 targets:
@@ -58,15 +79,61 @@ targets:
         - test/**.browser_test.dart
         - web/**.dart
         options:
-          compiler: dart2js
-          # List any dart2js specific args here, or omit it.
-          dart2js_args:
-          - -O2
+          compilers:
+            # All compilers listed here are enabled:
+            dart2js:
+              # List any dart2js specific args here, or omit it.
+              args:
+                - O2
+            dart2wasm:
+              args:
+                - O3
+```
+
+`build_runner` runs development builds by default, but can use builders with a
+different configuration for `--release` builds. For instance, if you wanted to
+compile with `dartdevc` only on development and `dart2js` + `dart2wasm` for
+release builds, you can use this configuration as a starting point:
+
+```yaml
+targets:
+  $default:
+    builders:
+      build_web_compilers:entrypoint:
+        generate_for:
+        - test/**.browser_test.dart
+        - web/**.dart
+        dev_options:
+          compilers:
+            dartdevc:
+        release_options:
+          compilers:
+            dart2js:
+              args:
+                - O2
+            dart2wasm:
+              args:
+                - O3
 ```
 
-In addition to DDC and dart2js, this package also supports the dart2wasm
-compiler for compiling to WebAssembly with a JavaScript loader. It can be
-enabled by using `compiler: dart2wasm` in the build configuration:
+### Customizing emitted file names
+
+The file names emitted by `build_web_compilers` can be changed. The default
+names depend on which compilers are enabled:
+
+1. When only `dart2js` or `dartdevc` is enabled, a single `.dart.js` entrypoint
+   is emitted.
+2. When only `dart2wasm` is enabled, a single `.dart.js` entrypoint (loading
+   a generated `.wasm` module through a `.mjs` helper file) is generated.
+3. When both `dart2wasm` and a JavaScript compiler are enabled, then:
+   - The output of the JavaScript compiler is named `.dart2js.js` or `.ddc.js`
+     depending on the compiler.
+   - `dart2wasm` continues to emit a `.wasm` and a `.mjs` file.
+   - An entrypoint loader named `.dart.js` that loads the appropriate output
+     depending on browser features is generated.
+
+All names can be overridden by using the `loader` option or the `extension`
+flag in compiler options:
 
 ```yaml
 targets:
@@ -74,12 +141,41 @@ targets:
     builders:
       build_web_compilers:entrypoint:
         options:
-          compiler: dart2wasm
-          # List flags that should be forwarded to `dart compile wasm`
-          dart2wasm_args:
-          - -O2
+          loader: .load.js
+          compilers:
+            dart2js:
+              extension: .old.js
+            dart2wasm:
+              extension: .new.mjs
+```
+
+This configuration uses both `dart2js` and `dart2wasm`, but names the final
+entrypoint for a `main.dart` file `main.load.js`. That loader will either load
+a `.new.mjs` file for WebAssembly or a `.old.js` for pure JavaScript.
+
+Note that the `loader` option is ignored when `dart2wasm` is not enabled, as
+it's the compiler requiring an additional loader to be emitted.
+
+### Customizing the WebAssembly loader
+
+In some cases, for instance when targeting Node.JS, the generated loader for
+`dart2wasm` may be unsuitable. The builtin loader can be disabled by setting
+the option to null:
+
+```yaml
+targets:
+  $default:
+    builders:
+      build_web_compilers:entrypoint:
+        options:
+          loader: null
+          compilers:
+            dart2js:
+            dart2wasm:
 ```
 
+In this case, you need to use another builder or a predefined loader instead.
+
 ### Configuring -D environment variables
 
 dartdevc is a modular compiler, so in order to ensure consistent builds
@@ -96,8 +192,30 @@ global_options:
         ANOTHER_VAR: false
 ```
 
-For dart2js, use the `dart2js_args` option. This may be configured globally, or
-per target.
+These may also be specified on the command line with a `--define` argument.
+
+```sh
+webdev serve -- '--define=build_web_compilers:ddc=environment={"SOME_VAR":"changed"}'
+```
+
+For dart2js, use the `args` option within the `dart2js` compiler entry. This
+may be configured globally, or per target.
+
+```yaml
+targets:
+  $default:
+    builders:
+      build_web_compilers:entrypoint:
+        options:
+          compilers:
+            dart2js:
+              args:
+                - -DSOME_VAR=some value
+                - -DANOTHER_VAR=true
+```
+
+To apply variables across multiple compilers, they have to be added to each
+one:
 
 ```yaml
 targets:
@@ -105,13 +223,40 @@ targets:
     builders:
       build_web_compilers:entrypoint:
         options:
+          compilers:
+            dart2js:
+              args:
+                - -DSOME_VAR=some value
+                - -DANOTHER_VAR=true
+            dart2wasm:
+              args:
+                - -DSOME_VAR=some value
+                - -DANOTHER_VAR=true
+```
+
+### Legacy builder options
+
+Previous versions of `build_web_compilers` only supported a single enabled
+compiler that would be enabled with the `compiler` option.
+If you only want to use `dart2js` for all builds, you can use that option:
+
+```yaml
+targets:
+  $default:
+    builders:
+      build_web_compilers:entrypoint:
+        # These are globs for the entrypoints you want to compile.
+        generate_for:
+        - test/**.browser_test.dart
+        - web/**.dart
+        options:
+          compiler: dart2js
+          # List any dart2js specific args here, or omit it.
           dart2js_args:
-          - -DSOME_VAR=some value
-          - -DANOTHER_VAR=true
+          - -O2
 ```
 
-Similarly, options are passed to `dart compile wasm` when using the
-`dart2wasm_args` option:
+Similarly, only compiling with `dart2wasm`:
 
 ```yaml
 targets:
@@ -120,16 +265,15 @@ targets:
       build_web_compilers:entrypoint:
         options:
           compiler: dart2wasm
+          # List flags that should be forwarded to `dart compile wasm`
           dart2wasm_args:
-          - -DSOME_VAR=some value
-          - -DANOTHER_VAR=true
+          - -O2
 ```
 
-These may also be specified on the command line with a `--define` argument.
-
-```sh
-webdev serve -- '--define=build_web_compilers:ddc=environment={"SOME_VAR":"changed"}'
-```
+When no option is set, the `compiler` option is implicitly set to `dart2js` on
+release builds and to `dartdevc` otherwise.
+Note that the `compilers` option takes precedence over the `compiler` option
+when set.
 
 ## Manual Usage
 
diff --git a/build_web_compilers/lib/src/dart2js_bootstrap.dart b/build_web_compilers/lib/src/dart2js_bootstrap.dart
index 4c0b1eba4..b37e76080 100644
--- a/build_web_compilers/lib/src/dart2js_bootstrap.dart
+++ b/build_web_compilers/lib/src/dart2js_bootstrap.dart
@@ -25,14 +25,20 @@ Future<void> bootstrapDart2Js(
   BuildStep buildStep,
   List<String> dart2JsArgs, {
   required bool? nativeNullAssertions,
+  String entrypointExtension = jsEntrypointExtension,
 }) =>
-    _resourcePool.withResource(() => _bootstrapDart2Js(buildStep, dart2JsArgs,
-        nativeNullAssertions: nativeNullAssertions));
+    _resourcePool.withResource(() => _bootstrapDart2Js(
+          buildStep,
+          dart2JsArgs,
+          nativeNullAssertions: nativeNullAssertions,
+          entrypointExtension: entrypointExtension,
+        ));
 
 Future<void> _bootstrapDart2Js(
   BuildStep buildStep,
   List<String> dart2JsArgs, {
   required bool? nativeNullAssertions,
+  required String entrypointExtension,
 }) async {
   var dartEntrypointId = buildStep.inputId;
   var moduleId =
@@ -74,7 +80,7 @@ https://github.com/dart-lang/build/blob/master/docs/faq.md#how-can-i-resolve-ski
     var jsOutputPath = p.withoutExtension(dartUri.scheme == 'package'
             ? 'packages/${dartUri.path}'
             : dartUri.path.substring(1)) +
-        jsEntrypointExtension;
+        entrypointExtension;
     var librariesSpec = p.joinAll([sdkDir, 'lib', 'libraries.json']);
     _validateUserArgs(dart2JsArgs);
     args = dart2JsArgs.toList()
@@ -102,7 +108,7 @@ https://github.com/dart-lang/build/blob/master/docs/faq.md#how-can-i-resolve-ski
         ...args,
       ],
       workingDirectory: scratchSpace.tempDir.path);
-  var jsOutputId = dartEntrypointId.changeExtension(jsEntrypointExtension);
+  var jsOutputId = dartEntrypointId.changeExtension(entrypointExtension);
   var jsOutputFile = scratchSpace.fileFor(jsOutputId);
   if (result.exitCode == 0 && await jsOutputFile.exists()) {
     log.info('${result.stdout}\n${result.stderr}');
@@ -111,7 +117,7 @@ https://github.com/dart-lang/build/blob/master/docs/faq.md#how-can-i-resolve-ski
     var fileGlob = Glob('$dartFile.js*');
     var archive = Archive();
     await for (var jsFile in fileGlob.list(root: rootDir)) {
-      if (jsFile.path.endsWith(jsEntrypointExtension) ||
+      if (jsFile.path.endsWith(entrypointExtension) ||
           jsFile.path.endsWith(jsEntrypointSourceMapExtension)) {
         // These are explicitly output, and are not part of the archive.
         continue;
diff --git a/build_web_compilers/lib/src/dart2wasm_bootstrap.dart b/build_web_compilers/lib/src/dart2wasm_bootstrap.dart
index 7f32202b3..51eb99bad 100644
--- a/build_web_compilers/lib/src/dart2wasm_bootstrap.dart
+++ b/build_web_compilers/lib/src/dart2wasm_bootstrap.dart
@@ -19,15 +19,22 @@ final _resourcePool = Pool(maxWorkersPerTask);
 
 /// Invokes `dart compile wasm` to compile the primary input of [buildStep].
 ///
-/// Additionally, generates a `.js` entrypoint file invoking the entrypoint.
+/// This only emits the `.wasm` and `.mjs` files produced by `dart2wasm`. An
+/// entrypoint loader needs to be emitted separately.
 Future<void> bootstrapDart2Wasm(
-    BuildStep buildStep, List<String> additionalArguments) async {
-  await _resourcePool
-      .withResource(() => _bootstrapDart2Wasm(buildStep, additionalArguments));
+  BuildStep buildStep,
+  List<String> additionalArguments,
+  String javaScriptModuleExtension,
+) async {
+  await _resourcePool.withResource(() => _bootstrapDart2Wasm(
+      buildStep, additionalArguments, javaScriptModuleExtension));
 }
 
 Future<void> _bootstrapDart2Wasm(
-    BuildStep buildStep, List<String> additionalArguments) async {
+  BuildStep buildStep,
+  List<String> additionalArguments,
+  String javaScriptModuleExtension,
+) async {
   var dartEntrypointId = buildStep.inputId;
   var moduleId =
       dartEntrypointId.changeExtension(moduleExtension(dart2wasmPlatform));
@@ -100,33 +107,17 @@ https://github.com/dart-lang/build/blob/master/docs/faq.md#how-can-i-resolve-ski
   if (result.exitCode == 0 && await wasmOutputFile.exists()) {
     log.info('${result.stdout}\n${result.stderr}');
 
-    for (final extension in [wasmExtension, moduleJsExtension]) {
-      await scratchSpace.copyOutput(
-          dartEntrypointId.changeExtension(extension), buildStep);
-    }
+    await scratchSpace.copyOutput(
+        dartEntrypointId.changeExtension(wasmExtension), buildStep);
 
-    final entrypoint = _entrypointRunner(buildStep.inputId);
-    await buildStep.writeAsString(entrypoint.$1, entrypoint.$2);
+    final loaderContents = await scratchSpace
+        .fileFor(dartEntrypointId.changeExtension(moduleJsExtension))
+        .readAsBytes();
+    await buildStep.writeAsBytes(
+        dartEntrypointId.changeExtension(javaScriptModuleExtension),
+        loaderContents);
   } else {
     log.severe('ExitCode:${result.exitCode}\nStdOut:\n${result.stdout}\n'
         'StdErr:\n${result.stderr}');
   }
 }
-
-(AssetId, String) _entrypointRunner(AssetId wasmSource) {
-  final id = wasmSource.changeExtension('.dart.js');
-  final basename = p.url.basenameWithoutExtension(wasmSource.path);
-
-  return (
-    id,
-    '''
-(async () => {
-  let { instantiate, invoke } = await import("./$basename.mjs");
-
-  let modulePromise = WebAssembly.compileStreaming(fetch("$basename.wasm"));
-  let instantiated = await instantiate(modulePromise, {});
-  invoke(instantiated, []);
-})();
-'''
-  );
-}
diff --git a/build_web_compilers/lib/src/dev_compiler_bootstrap.dart b/build_web_compilers/lib/src/dev_compiler_bootstrap.dart
index 2e2b8dfb4..a0223c32f 100644
--- a/build_web_compilers/lib/src/dev_compiler_bootstrap.dart
+++ b/build_web_compilers/lib/src/dev_compiler_bootstrap.dart
@@ -31,6 +31,7 @@ Future<void> bootstrapDdc(
   BuildStep buildStep, {
   DartPlatform? platform,
   Iterable<AssetId> requiredAssets = const [],
+  String entrypointExtension = jsEntrypointExtension,
   required bool? nativeNullAssertions,
 }) async {
   platform = ddcPlatform;
@@ -132,7 +133,7 @@ https://github.com/dart-lang/build/blob/master/docs/faq.md#how-can-i-resolve-ski
 
   var entrypointJsContent = _entryPointJs(bootstrapModuleName);
   await buildStep.writeAsString(
-      dartEntrypointId.changeExtension(jsEntrypointExtension),
+      dartEntrypointId.changeExtension(entrypointExtension),
       entrypointJsContent);
 
   // Output the digests and merged_metadata for transitive modules.
diff --git a/build_web_compilers/lib/src/web_entrypoint_builder.dart b/build_web_compilers/lib/src/web_entrypoint_builder.dart
index 671f8b888..b3bad5a4b 100644
--- a/build_web_compilers/lib/src/web_entrypoint_builder.dart
+++ b/build_web_compilers/lib/src/web_entrypoint_builder.dart
@@ -8,6 +8,8 @@ import 'package:analyzer/dart/analysis/utilities.dart';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:build/build.dart';
 import 'package:build_modules/build_modules.dart';
+import 'package:collection/collection.dart';
+import 'package:path/path.dart' as p;
 
 import 'common.dart';
 import 'dart2js_bootstrap.dart';
@@ -26,16 +28,45 @@ const mergedMetadataExtension = '.dart.ddc_merged_metadata';
 /// Which compiler to use when compiling web entrypoints.
 enum WebCompiler {
   // ignore: constant_identifier_names
-  Dart2Js('dart2js'),
+  Dart2Js(
+    'dart2js',
+    entrypointExtensionWhenOnlyCompiler: jsEntrypointExtension,
+    entrypointExtension: '.dart2js.js',
+  ),
   // ignore: constant_identifier_names
-  DartDevc('dartdevc'),
+  DartDevc(
+    'dartdevc',
+    entrypointExtensionWhenOnlyCompiler: jsEntrypointExtension,
+    entrypointExtension: '.ddc.js',
+  ),
   // ignore: constant_identifier_names
-  Dart2Wasm('dart2wasm');
+  Dart2Wasm(
+    'dart2wasm',
+    entrypointExtensionWhenOnlyCompiler: moduleJsExtension,
+    entrypointExtension: moduleJsExtension,
+  );
 
   /// The name of this compiler used when identifying it in builder options.
   final String optionName;
 
-  const WebCompiler(this.optionName);
+  /// The [EnabledEntrypointCompiler.extension] to use when this compiler is the
+  /// only compiler enabled.
+  /// This defaults to `.dart.js` for compilers targeting JavaScript and `.mjs`
+  /// for the module file emitted by `dart2wasm`.
+  final String entrypointExtensionWhenOnlyCompiler;
+
+  /// The [EnabledEntrypointCompiler.extension] to use by default when multiple
+  /// compilers are enabled.
+  ///
+  /// This can't be `.dart.js` for multiple web compilers because we'd then run
+  /// into duplicate outputs being generated.
+  final String entrypointExtension;
+
+  const WebCompiler(
+    this.optionName, {
+    required this.entrypointExtensionWhenOnlyCompiler,
+    required this.entrypointExtension,
+  });
 
   static WebCompiler fromOptionName(String name) {
     for (final compiler in values) {
@@ -48,39 +79,26 @@ enum WebCompiler {
 
     throw ArgumentError.value(
       name,
-      _compilerOption,
+      null,
       'Unknown web compiler, supported are: $supported.',
     );
   }
 }
 
-/// The top level keys supported for the `options` config for the
-/// [WebEntrypointBuilder].
-const _supportedOptions = [
-  _compilerOption,
-  _dart2jsArgsOption,
-  _nativeNullAssertionsOption,
-  _dart2wasmArgsOption,
-];
-
-const _compilerOption = 'compiler';
-const _dart2jsArgsOption = 'dart2js_args';
-const _dart2wasmArgsOption = 'dart2wasm_args';
-const _nativeNullAssertionsOption = 'native_null_assertions';
+final class EnabledEntrypointCompiler {
+  final WebCompiler compiler;
+  final String extension;
+  final List<String> compilerArguments;
 
-/// The deprecated keys for the `options` config for the [WebEntrypointBuilder].
-const _deprecatedOptions = [
-  'enable_sync_async',
-  'ignore_cast_failures',
-];
+  EnabledEntrypointCompiler({
+    required this.compiler,
+    required this.extension,
+    required this.compilerArguments,
+  });
+}
 
-/// A builder which compiles entrypoints for the web.
-///
-/// Supports `dart2js` and `dartdevc`.
-class WebEntrypointBuilder implements Builder {
-  final WebCompiler webCompiler;
-  final List<String> dart2JsArgs;
-  final List<String> dart2WasmArgs;
+final class EntrypointBuilderOptions {
+  final List<EnabledEntrypointCompiler> compilers;
 
   /// Whether or not to enable runtime non-null assertions for values returned
   /// from browser apis.
@@ -89,69 +107,152 @@ class WebEntrypointBuilder implements Builder {
   /// will be used.
   final bool? nativeNullAssertions;
 
-  const WebEntrypointBuilder(
-    this.webCompiler, {
-    this.dart2JsArgs = const [],
-    this.dart2WasmArgs = const [],
-    required this.nativeNullAssertions,
+  /// dart2wasm emits a WebAssembly module and a `.mjs` file exporting symbols
+  /// to instantiate that module.
+  ///
+  /// To generate a runnable entrypoint file, a loader will have to load the
+  /// `.mjs` module and invoke the exported methods.
+  /// This loader can be generated by `build_web_compilers` (and is by default
+  /// if dart2wasm is enabled), but this can be turned off for users which need
+  /// a custom way to load WebAssembly modules (e.g. to target Node.JS).
+  /// When multiple compilers are enabled (typically dart2js + dart2wasm) for
+  /// release builds, the loader file is also responsible for running a feature
+  /// detection, preferring WebAssembly but falling back to JavaScript if
+  /// necessary.
+  final String? loaderExtension;
+
+  EntrypointBuilderOptions({
+    required this.compilers,
+    this.nativeNullAssertions,
+    this.loaderExtension,
   });
 
-  factory WebEntrypointBuilder.fromOptions(BuilderOptions options) {
-    validateOptions(
-        options.config, _supportedOptions, 'build_web_compilers:entrypoint',
-        deprecatedOptions: _deprecatedOptions);
-    var compilerOption =
-        options.config[_compilerOption] as String? ?? 'dartdevc';
-    var compiler = WebCompiler.fromOptionName(compilerOption);
-
-    return WebEntrypointBuilder(
-      compiler,
-      dart2JsArgs: _parseCompilerOptions(options, _dart2jsArgsOption),
-      dart2WasmArgs: _parseCompilerOptions(options, _dart2wasmArgsOption),
-      nativeNullAssertions:
-          options.config[_nativeNullAssertionsOption] as bool?,
+  factory EntrypointBuilderOptions.fromOptions(BuilderOptions options) {
+    const deprecatedOptions = [
+      'enable_sync_async',
+      'ignore_cast_failures',
+    ];
+
+    const compilerOption = 'compiler';
+    const compilersOption = 'compilers';
+    const dart2jsArgsOption = 'dart2js_args';
+    const dart2wasmArgsOption = 'dart2wasm_args';
+    const nativeNullAssertionsOption = 'native_null_assertions';
+    const loaderOption = 'loader';
+    String? defaultLoaderOption;
+
+    const supportedOptions = [
+      compilersOption,
+      compilerOption,
+      dart2jsArgsOption,
+      nativeNullAssertionsOption,
+      dart2wasmArgsOption,
+      loaderOption,
+    ];
+
+    var config = options.config;
+    var nativeNullAssertions =
+        options.config[nativeNullAssertionsOption] as bool?;
+    var compilers = <EnabledEntrypointCompiler>[];
+
+    validateOptions(config, supportedOptions, 'build_web_compilers:entrypoint',
+        deprecatedOptions: deprecatedOptions);
+
+    // The compilers option is a map of compiler names to options only applying
+    // to that compiler, which allows compiling with multiple compilers (e.g.
+    // dart2js + dart2wasm). Since the default builder configuration doesn't
+    // use the compilers key, we preserve backwards compatibility.
+    if (config.containsKey(compilersOption)) {
+      var configuredCompilers = (config[compilersOption] as Map?)
+              ?.cast<String, Map<String, Object?>?>() ??
+          const {};
+      var hasDart2Wasm = false;
+
+      for (var MapEntry(:key, :value) in configuredCompilers.entries) {
+        const extensionOption = 'extension';
+        const argsOption = 'args';
+        const supportedOptions = [extensionOption, argsOption];
+        validateOptions(value ?? const {}, supportedOptions,
+            'build_web_compilers:entrypoint');
+
+        var compiler = WebCompiler.fromOptionName(key);
+        compilers.add(EnabledEntrypointCompiler(
+          compiler: compiler,
+          extension: value?[extensionOption] as String? ??
+              (configuredCompilers.length == 1
+                  ? compiler.entrypointExtensionWhenOnlyCompiler
+                  : compiler.entrypointExtension),
+          compilerArguments: _parseCompilerOptions(
+              value?[argsOption], '$compilersOption.$key'),
+        ));
+
+        hasDart2Wasm |= compiler == WebCompiler.Dart2Wasm;
+      }
+
+      if (hasDart2Wasm) {
+        defaultLoaderOption = '.dart.js';
+      }
+    } else {
+      var compilerName = config[compilerOption] as String? ?? 'dartdevc';
+
+      var compiler = WebCompiler.fromOptionName(compilerName);
+      compilers.add(EnabledEntrypointCompiler(
+        compiler: compiler,
+        extension: compiler.entrypointExtensionWhenOnlyCompiler,
+        compilerArguments: switch (compiler) {
+          WebCompiler.DartDevc => const [],
+          WebCompiler.Dart2Js =>
+            _parseCompilerOptions(config[dart2jsArgsOption], dart2jsArgsOption),
+          WebCompiler.Dart2Wasm => _parseCompilerOptions(
+              config[dart2wasmArgsOption], dart2wasmArgsOption),
+        },
+      ));
+
+      if (compiler == WebCompiler.Dart2Wasm) {
+        // dart2wasm needs a custom loader script to work as an entrypoint, so
+        // enable one by default if dart2wasm is configured as compiler.
+        defaultLoaderOption = '.dart.js';
+      }
+    }
+
+    return EntrypointBuilderOptions(
+      compilers: compilers,
+      nativeNullAssertions: nativeNullAssertions,
+      loaderExtension: config.containsKey(loaderOption)
+          ? config[loaderOption] as String?
+          : defaultLoaderOption,
     );
   }
 
-  @override
-  final buildExtensions = const {
-    '.dart': [
-      ddcBootstrapExtension,
-      jsEntrypointExtension,
-      jsEntrypointSourceMapExtension,
-      jsEntrypointArchiveExtension,
-      digestsEntrypointExtension,
-      mergedMetadataExtension,
-      wasmExtension,
-      moduleJsExtension,
-    ],
-  };
+  EnabledEntrypointCompiler? optionsFor(WebCompiler compiler) {
+    return compilers.firstWhereOrNull((c) => c.compiler == compiler);
+  }
 
-  @override
-  Future<void> build(BuildStep buildStep) async {
-    var dartEntrypointId = buildStep.inputId;
-    var isAppEntrypoint = await _isAppEntryPoint(dartEntrypointId, buildStep);
-    if (!isAppEntrypoint) return;
-    switch (webCompiler) {
-      case WebCompiler.DartDevc:
-        try {
-          await bootstrapDdc(buildStep,
-              nativeNullAssertions: nativeNullAssertions,
-              requiredAssets: _ddcSdkResources);
-        } on MissingModulesException catch (e) {
-          log.severe('$e');
-        }
-      case WebCompiler.Dart2Js:
-        await bootstrapDart2Js(buildStep, dart2JsArgs,
-            nativeNullAssertions: nativeNullAssertions);
-      case WebCompiler.Dart2Wasm:
-        await bootstrapDart2Wasm(buildStep, dart2WasmArgs);
-    }
+  Map<String, List<String>> get buildExtensions {
+    return {
+      '.dart': [
+        if (optionsFor(WebCompiler.DartDevc) case final ddc?) ...[
+          ddcBootstrapExtension,
+          mergedMetadataExtension,
+          digestsEntrypointExtension,
+          ddc.extension,
+        ],
+        if (optionsFor(WebCompiler.Dart2Js) case final dart2js?) ...[
+          dart2js.extension,
+          jsEntrypointSourceMapExtension,
+          jsEntrypointArchiveExtension,
+        ],
+        if (optionsFor(WebCompiler.Dart2Wasm) case final dart2wasm?) ...[
+          dart2wasm.extension,
+          wasmExtension,
+        ],
+        if (loaderExtension case final loader?) loader,
+      ]
+    };
   }
 
-  static List<String> _parseCompilerOptions(
-      BuilderOptions options, String key) {
-    return switch (options.config[key]) {
+  static List<String> _parseCompilerOptions(Object? from, String key) {
+    return switch (from) {
       null => const [],
       List list => list.map((arg) => '$arg').toList(),
       String other => throw ArgumentError.value(
@@ -164,6 +265,123 @@ class WebEntrypointBuilder implements Builder {
   }
 }
 
+/// The deprecated keys for the `options` config for the [WebEntrypointBuilder].
+
+/// A builder which compiles entrypoints for the web.
+///
+/// Supports `dart2js` and `dartdevc`.
+class WebEntrypointBuilder implements Builder {
+  final EntrypointBuilderOptions options;
+
+  const WebEntrypointBuilder(this.options);
+
+  factory WebEntrypointBuilder.fromOptions(BuilderOptions options) {
+    return WebEntrypointBuilder(EntrypointBuilderOptions.fromOptions(options));
+  }
+
+  @override
+  Map<String, List<String>> get buildExtensions => options.buildExtensions;
+
+  @override
+  Future<void> build(BuildStep buildStep) async {
+    var dartEntrypointId = buildStep.inputId;
+    var isAppEntrypoint = await _isAppEntryPoint(dartEntrypointId, buildStep);
+    if (!isAppEntrypoint) return;
+
+    final compilationSteps = <Future>[];
+
+    for (final compiler in options.compilers) {
+      switch (compiler.compiler) {
+        case WebCompiler.DartDevc:
+          compilationSteps.add(Future(() async {
+            try {
+              await bootstrapDdc(buildStep,
+                  nativeNullAssertions: options.nativeNullAssertions,
+                  requiredAssets: _ddcSdkResources);
+            } on MissingModulesException catch (e) {
+              log.severe('$e');
+            }
+          }));
+        case WebCompiler.Dart2Js:
+          compilationSteps.add(bootstrapDart2Js(
+            buildStep,
+            compiler.compilerArguments,
+            nativeNullAssertions: options.nativeNullAssertions,
+            entrypointExtension: compiler.extension,
+          ));
+        case WebCompiler.Dart2Wasm:
+          compilationSteps.add(bootstrapDart2Wasm(
+              buildStep, compiler.compilerArguments, compiler.extension));
+      }
+    }
+    await Future.wait(compilationSteps);
+    if (_generateLoader(buildStep.inputId) case (var id, var loader)?) {
+      await buildStep.writeAsString(id, loader);
+    }
+  }
+
+  (AssetId, String)? _generateLoader(AssetId input) {
+    var loaderExtension = options.loaderExtension;
+    var wasmCompiler = options.optionsFor(WebCompiler.Dart2Wasm);
+    if (loaderExtension == null || wasmCompiler == null) {
+      // Generating the loader has been disabled or no loader is necessary.
+      return null;
+    }
+
+    var loaderId = input.changeExtension(options.loaderExtension!);
+    var basename = p.url.basenameWithoutExtension(input.path);
+
+    // Are we compiling to JavaScript in addition to wasm?
+    var jsCompiler = options.optionsFor(WebCompiler.Dart2Js) ??
+        options.optionsFor(WebCompiler.DartDevc);
+
+    var loaderResult = StringBuffer('''(async () => {
+function resolveUrlWithSegments(...segments) {
+  return new URL(joinPathSegments(...segments), document.baseURI).toString()
+}
+''');
+
+    // If we're compiling to JS, start a feature detection to prefer wasm but
+    // fall back to JS if necessary.
+    if (jsCompiler != null) {
+      loaderResult.writeln('''
+function supportsWasmGC() {
+  // This attempts to instantiate a wasm module that only will validate if the
+  // final WasmGC spec is implemented in the browser.
+  //
+  // Copied from https://github.com/GoogleChromeLabs/wasm-feature-detect/blob/main/src/detectors/gc/index.js
+  const bytes = [0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 95, 1, 120, 0];
+  return WebAssembly && WebAssembly.validate(new Uint8Array(bytes));
+}
+
+if (supportsWasmGC()) {
+''');
+    }
+
+    loaderResult.writeln('''
+let { instantiate, invoke } = await import("./$basename${wasmCompiler.extension}");
+
+let modulePromise = WebAssembly.compileStreaming(fetch("$basename.wasm"));
+let instantiated = await instantiate(modulePromise, {});
+invoke(instantiated, []);
+''');
+
+    if (jsCompiler != null) {
+      loaderResult.writeln('''
+} else {
+const scriptTag = document.createElement("script");
+scriptTag.type = "application/javascript";
+scriptTag.src = resolveUrlWithSegments("./$basename${jsCompiler.extension}");
+document.head.append(scriptTag);
+}
+''');
+    }
+
+    loaderResult.writeln('})();');
+    return (loaderId, loaderResult.toString());
+  }
+}
+
 /// Returns whether or not [dartId] is an app entrypoint (basically, whether
 /// or not it has a `main` function).
 Future<bool> _isAppEntryPoint(AssetId dartId, AssetReader reader) async {
diff --git a/build_web_compilers/pubspec.yaml b/build_web_compilers/pubspec.yaml
index b30a0ed2c..efc140c28 100644
--- a/build_web_compilers/pubspec.yaml
+++ b/build_web_compilers/pubspec.yaml
@@ -1,5 +1,5 @@
 name: build_web_compilers
-version: 4.0.12-wip
+version: 4.1.0-wip
 description: Builder implementations wrapping the dart2js and DDC compilers.
 repository: https://github.com/dart-lang/build/tree/master/build_web_compilers
 # This package can't be part of the workspace because it requires a very recent
diff --git a/build_web_compilers/test/dart2js_bootstrap_test.dart b/build_web_compilers/test/dart2js_bootstrap_test.dart
index ff931a413..502937b6a 100644
--- a/build_web_compilers/test/dart2js_bootstrap_test.dart
+++ b/build_web_compilers/test/dart2js_bootstrap_test.dart
@@ -4,6 +4,7 @@
 
 import 'dart:async';
 
+import 'package:build/build.dart';
 import 'package:build_modules/build_modules.dart';
 import 'package:build_test/build_test.dart';
 import 'package:build_web_compilers/build_web_compilers.dart';
@@ -59,8 +60,10 @@ void main() {
         'a|web/index.dart.js.tar.gz': anything,
       };
       await testBuilder(
-          const WebEntrypointBuilder(WebCompiler.Dart2Js,
-              nativeNullAssertions: false),
+          WebEntrypointBuilder.fromOptions(const BuilderOptions({
+            'compiler': 'dart2js',
+            'native_null_assertions': false,
+          })),
           assets,
           outputs: expectedOutputs);
     });
@@ -71,8 +74,11 @@ void main() {
         'a|web/index.dart.js.tar.gz': anything,
       };
       await testBuilder(
-          const WebEntrypointBuilder(WebCompiler.Dart2Js,
-              dart2JsArgs: ['--no-source-maps'], nativeNullAssertions: false),
+          WebEntrypointBuilder.fromOptions(const BuilderOptions({
+            'compiler': 'dart2js',
+            'native_null_assertions': false,
+            'dart2js_args': ['--no-source-maps']
+          })),
           assets,
           outputs: expectedOutputs);
     });
@@ -101,8 +107,10 @@ void main() {
       'a|lib/index.dart.js.tar.gz': anything,
     };
     await testBuilder(
-        const WebEntrypointBuilder(WebCompiler.Dart2Js,
-            nativeNullAssertions: false),
+        WebEntrypointBuilder.fromOptions(const BuilderOptions({
+          'compiler': 'dart2js',
+          'native_null_assertions': false,
+        })),
         assets,
         outputs: expectedOutputs);
   });
diff --git a/build_web_compilers/test/dart2wasm_bootstrap_test.dart b/build_web_compilers/test/dart2wasm_bootstrap_test.dart
new file mode 100644
index 000000000..3d40139f0
--- /dev/null
+++ b/build_web_compilers/test/dart2wasm_bootstrap_test.dart
@@ -0,0 +1,103 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:build/build.dart';
+import 'package:build_modules/build_modules.dart';
+import 'package:build_test/build_test.dart';
+import 'package:build_web_compilers/build_web_compilers.dart';
+import 'package:test/test.dart';
+
+import 'util.dart';
+
+void main() {
+  late Map<String, Object> assets;
+
+  setUp(() async {
+    assets = {
+      'a|web/index.dart': '''
+        void main() {
+          print('Hello world!');
+        }
+      ''',
+    };
+
+    // Set up all the other required inputs for this test.
+    await testBuilderAndCollectAssets(const ModuleLibraryBuilder(), assets);
+    for (final platform in [dart2jsPlatform, dart2wasmPlatform]) {
+      await testBuilderAndCollectAssets(MetaModuleBuilder(platform), assets);
+      await testBuilderAndCollectAssets(
+          MetaModuleCleanBuilder(platform), assets);
+      await testBuilderAndCollectAssets(ModuleBuilder(platform), assets);
+    }
+  });
+
+  group('generates loader script', () {
+    test('with old compiler option', () async {
+      await testBuilder(
+        WebEntrypointBuilder.fromOptions(
+            const BuilderOptions({'compiler': 'dart2wasm'})),
+        assets,
+        outputs: {
+          'a|web/index.mjs': anything,
+          'a|web/index.wasm': anything,
+          'a|web/index.dart.js':
+              decodedMatches(contains('WebAssembly.compileStreaming')),
+        },
+      );
+    });
+
+    test('when using both dart2wasm and dart2js', () async {
+      await testBuilder(
+        WebEntrypointBuilder.fromOptions(
+          const BuilderOptions(
+            {
+              'compilers': {
+                'dart2js': <String, Object?>{},
+                'dart2wasm': <String, Object?>{},
+              },
+            },
+          ),
+        ),
+        assets,
+        outputs: {
+          'a|web/index.mjs': anything,
+          'a|web/index.wasm': anything,
+          'a|web/index.dart2js.js': decodedMatches(contains('Hello world!')),
+          'a|web/index.dart.js': decodedMatches(
+            stringContainsInOrder(
+              [
+                'if (supportsWasmGC())',
+                'WebAssembly.compileStreaming',
+                'else',
+                'scriptTag.src = resolveUrlWithSegments("./index.dart2js.js");'
+              ],
+            ),
+          ),
+        },
+      );
+    });
+  });
+
+  test('can disable generation of loader script', () async {
+    await testBuilder(
+      WebEntrypointBuilder.fromOptions(
+        const BuilderOptions(
+          {
+            'compilers': {
+              'dart2js': <String, Object?>{},
+              'dart2wasm': <String, Object?>{},
+            },
+            'loader': null,
+          },
+        ),
+      ),
+      assets,
+      outputs: {
+        'a|web/index.mjs': anything,
+        'a|web/index.wasm': anything,
+        'a|web/index.dart2js.js': decodedMatches(contains('Hello world!')),
+      },
+    );
+  });
+}
diff --git a/build_web_compilers/test/dev_compiler_bootstrap_test.dart b/build_web_compilers/test/dev_compiler_bootstrap_test.dart
index b2889c4f8..3762f7994 100644
--- a/build_web_compilers/test/dev_compiler_bootstrap_test.dart
+++ b/build_web_compilers/test/dev_compiler_bootstrap_test.dart
@@ -54,8 +54,10 @@ void main() {
         ])),
       };
       await testBuilder(
-          const WebEntrypointBuilder(WebCompiler.DartDevc,
-              nativeNullAssertions: false),
+          WebEntrypointBuilder.fromOptions(const BuilderOptions({
+            'compiler': 'dartdevc',
+            'native_null_assertions': false,
+          })),
           assets,
           outputs: expectedOutputs);
     });
@@ -93,8 +95,10 @@ void main() {
         'a|web/b.dart.js': isNotEmpty,
       };
       await testBuilder(
-          const WebEntrypointBuilder(WebCompiler.DartDevc,
-              nativeNullAssertions: false),
+          WebEntrypointBuilder.fromOptions(const BuilderOptions({
+            'compiler': 'dartdevc',
+            'native_null_assertions': false,
+          })),
           assets,
           outputs: expectedOutputs);
     });
@@ -116,8 +120,10 @@ void main() {
         'a|lib/app.dart.js': isNotEmpty,
       };
       await testBuilder(
-          const WebEntrypointBuilder(WebCompiler.DartDevc,
-              nativeNullAssertions: false),
+          WebEntrypointBuilder.fromOptions(const BuilderOptions({
+            'compiler': 'dartdevc',
+            'native_null_assertions': false,
+          })),
           assets,
           outputs: expectedOutputs);
     });
diff --git a/build_web_compilers/test/entrypoint_options_test.dart b/build_web_compilers/test/entrypoint_options_test.dart
new file mode 100644
index 000000000..2e5923de1
--- /dev/null
+++ b/build_web_compilers/test/entrypoint_options_test.dart
@@ -0,0 +1,97 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:build/build.dart';
+import 'package:build_web_compilers/src/web_entrypoint_builder.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('uses ddc by default', () {
+    final options =
+        EntrypointBuilderOptions.fromOptions(const BuilderOptions({}));
+    expect(options.compilers, [
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.DartDevc)
+          .having((e) => e.compilerArguments, 'compilerArguments', isEmpty)
+          .having((e) => e.extension, 'extension', '.dart.js')
+    ]);
+  });
+
+  test('parses old dart2js options', () {
+    final options = EntrypointBuilderOptions.fromOptions(const BuilderOptions({
+      'compiler': 'dart2js',
+      'dart2js_args': ['-O4'],
+    }));
+
+    expect(options.nativeNullAssertions, isNull);
+    expect(options.loaderExtension, isNull);
+    expect(options.compilers, [
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.Dart2Js)
+          .having((e) => e.compilerArguments, 'compilerArguments',
+              ['-O4']).having((e) => e.extension, 'extension', '.dart.js')
+    ]);
+  });
+
+  test('parses old ddc options', () {
+    final options = EntrypointBuilderOptions.fromOptions(const BuilderOptions({
+      'compiler': 'dartdevc',
+      'dart2js_args': ['-O4'],
+    }));
+
+    expect(options.nativeNullAssertions, isNull);
+    expect(options.loaderExtension, isNull);
+    expect(options.compilers, [
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.DartDevc)
+          .having((e) => e.compilerArguments, 'compilerArguments', isEmpty)
+          .having((e) => e.extension, 'extension', '.dart.js')
+    ]);
+  });
+
+  test('parses old dart2wasm options', () {
+    final options = EntrypointBuilderOptions.fromOptions(const BuilderOptions({
+      'compiler': 'dart2wasm',
+      'dart2wasm_args': ['-O4'],
+    }));
+
+    expect(options.nativeNullAssertions, isNull);
+    expect(options.loaderExtension, '.dart.js');
+    expect(options.compilers, [
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.Dart2Wasm)
+          .having((e) => e.compilerArguments, 'compilerArguments',
+              ['-O4']).having((e) => e.extension, 'extension', '.mjs')
+    ]);
+  });
+
+  test('can enable multiple compilers', () {
+    final options = EntrypointBuilderOptions.fromOptions(const BuilderOptions({
+      'compilers': {
+        'dart2js': {
+          'args': ['-O4'],
+        },
+        'dart2wasm': {
+          'extension': '.custom_extension.js',
+          'args': ['-O3'],
+        },
+      },
+      'loader': '.dart.js',
+    }));
+
+    expect(options.nativeNullAssertions, isNull);
+    expect(options.loaderExtension, '.dart.js');
+    expect(options.compilers, [
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.Dart2Js)
+          .having((e) => e.compilerArguments, 'compilerArguments',
+              ['-O4']).having((e) => e.extension, 'extension', '.dart2js.js'),
+      isA<EnabledEntrypointCompiler>()
+          .having((e) => e.compiler, 'compiler', WebCompiler.Dart2Wasm)
+          .having((e) => e.compilerArguments, 'compilerArguments', [
+        '-O3'
+      ]).having((e) => e.extension, 'extension', '.custom_extension.js'),
+    ]);
+  });
+}