From 37906d4dfbe80d71f312f7347bb9ddb930484d28 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 27 Jan 2025 12:39:56 -0800
Subject: [PATCH] [Flight Parcel] Pass import maps through client references
 (#32132)

Corresponding Parcel PR:
https://github.com/parcel-bundler/parcel/pull/10073

Parcel avoids [cascading cache
invalidation](https://philipwalton.com/articles/cascading-cache-invalidation/)
by injecting a bundle manifest containing a mapping of stable bundle ids
to hashed URLs. When using an HTML entry point, this is done (as of the
above PR) via a native import map. This means that if a bundle's hash
changes, only that bundle will be invalidated (plus the HTML itself
which typically has a short caching policy), not any other bundles that
reference it.

For RSCs, we cannot currently use native import maps because of client
side navigations, where a new HTML file is not requested. Eventually,
multiple `<script type="importmap">` elements will be supported
(https://github.com/whatwg/html/pull/10528) ([coming Chrome
133](https://chromestatus.com/feature/5121916248260608)), at which point
React could potentially inject them. In the meantime, I've added some
APIs to Parcel to polyfill this. With this change, an import map can be
sent along with a client reference, containing a mapping for any dynamic
imports and URL dependencies (e.g. images) that are referenced by the JS
bundles. On the client, the import map is extended with these new
mappings prior to executing the referenced bundles. This preserves the
caching advantages described above while supporting client navigations.
---
 .../src/ReactFlightParcelReferences.js               |  3 +++
 .../client/ReactFlightClientConfigBundlerParcel.js   | 12 +++++++++++-
 .../server/ReactFlightServerConfigParcelBundler.js   |  9 +++++++++
 .../src/shared/ReactFlightImportMetadata.js          | 11 ++++++++---
 scripts/flow/environment.js                          |  1 +
 5 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/packages/react-server-dom-parcel/src/ReactFlightParcelReferences.js b/packages/react-server-dom-parcel/src/ReactFlightParcelReferences.js
index 2e5ed24da2fd1..48560ae65350d 100644
--- a/packages/react-server-dom-parcel/src/ReactFlightParcelReferences.js
+++ b/packages/react-server-dom-parcel/src/ReactFlightParcelReferences.js
@@ -22,6 +22,7 @@ export type ClientReference<T> = {
   $$id: string,
   $$name: string,
   $$bundles: Array<string>,
+  $$importMap?: ?{[string]: string},
 };
 
 const CLIENT_REFERENCE_TAG = Symbol.for('react.client.reference');
@@ -39,12 +40,14 @@ export function createClientReference<T>(
   id: string,
   exportName: string,
   bundles: Array<string>,
+  importMap?: ?{[string]: string},
 ): ClientReference<T> {
   return {
     $$typeof: CLIENT_REFERENCE_TAG,
     $$id: id,
     $$name: exportName,
     $$bundles: bundles,
+    $$importMap: importMap,
   };
 }
 
diff --git a/packages/react-server-dom-parcel/src/client/ReactFlightClientConfigBundlerParcel.js b/packages/react-server-dom-parcel/src/client/ReactFlightClientConfigBundlerParcel.js
index 128ef9f5e15ed..1d380a3059108 100644
--- a/packages/react-server-dom-parcel/src/client/ReactFlightClientConfigBundlerParcel.js
+++ b/packages/react-server-dom-parcel/src/client/ReactFlightClientConfigBundlerParcel.js
@@ -11,7 +11,12 @@ import type {Thenable} from 'shared/ReactTypes';
 
 import type {ImportMetadata} from '../shared/ReactFlightImportMetadata';
 
-import {ID, NAME, BUNDLES} from '../shared/ReactFlightImportMetadata';
+import {
+  ID,
+  NAME,
+  BUNDLES,
+  IMPORT_MAP,
+} from '../shared/ReactFlightImportMetadata';
 import {prepareDestinationWithChunks} from 'react-client/src/ReactFlightClientConfig';
 
 export type ServerManifest = {
@@ -60,9 +65,14 @@ export function resolveServerReference<T>(
 export function preloadModule<T>(
   metadata: ClientReference<T>,
 ): null | Thenable<any> {
+  if (metadata[IMPORT_MAP]) {
+    parcelRequire.extendImportMap(metadata[IMPORT_MAP]);
+  }
+
   if (metadata[BUNDLES].length === 0) {
     return null;
   }
+
   return Promise.all(metadata[BUNDLES].map(url => parcelRequire.load(url)));
 }
 
diff --git a/packages/react-server-dom-parcel/src/server/ReactFlightServerConfigParcelBundler.js b/packages/react-server-dom-parcel/src/server/ReactFlightServerConfigParcelBundler.js
index 60bdf1612519c..ebcfec1badcf9 100644
--- a/packages/react-server-dom-parcel/src/server/ReactFlightServerConfigParcelBundler.js
+++ b/packages/react-server-dom-parcel/src/server/ReactFlightServerConfigParcelBundler.js
@@ -37,6 +37,15 @@ export function resolveClientReferenceMetadata<T>(
   config: ClientManifest,
   clientReference: ClientReference<T>,
 ): ClientReferenceMetadata {
+  if (clientReference.$$importMap) {
+    return [
+      clientReference.$$id,
+      clientReference.$$name,
+      clientReference.$$bundles,
+      clientReference.$$importMap,
+    ];
+  }
+
   return [
     clientReference.$$id,
     clientReference.$$name,
diff --git a/packages/react-server-dom-parcel/src/shared/ReactFlightImportMetadata.js b/packages/react-server-dom-parcel/src/shared/ReactFlightImportMetadata.js
index 4e329edf27251..d91f5d825c22b 100644
--- a/packages/react-server-dom-parcel/src/shared/ReactFlightImportMetadata.js
+++ b/packages/react-server-dom-parcel/src/shared/ReactFlightImportMetadata.js
@@ -10,11 +10,16 @@
 // This is the parsed shape of the wire format which is why it is
 // condensed to only the essentialy information
 export type ImportMetadata = [
-  /* id */ string,
-  /* name */ string,
-  /* bundles */ Array<string>,
+  // eslint does not understand Flow tuple syntax.
+  /* eslint-disable */
+  id: string,
+  name: string,
+  bundles: Array<string>,
+  importMap?: {[string]: string},
+  /* eslint-enable */
 ];
 
 export const ID = 0;
 export const NAME = 1;
 export const BUNDLES = 2;
+export const IMPORT_MAP = 3;
diff --git a/scripts/flow/environment.js b/scripts/flow/environment.js
index 1d4e6dbd9c7f1..37ca6fe4dc223 100644
--- a/scripts/flow/environment.js
+++ b/scripts/flow/environment.js
@@ -106,6 +106,7 @@ declare const __turbopack_require__: ((id: string) => any) & {
 declare var parcelRequire: {
   (id: string): any,
   load: (url: string) => Promise<mixed>,
+  extendImportMap: (importMap: {[string]: string}) => void,
   meta: {
     publicUrl: string,
   },