remote-components 0.2.0 → 0.2.2

package/dist/host/react.d.ts

@@ -1,366 +1,2 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-
-/**
- * Intercepts client-side URL resolution for remote component resources.
- * Called before each asset (script, stylesheet, chunk, module, image) is fetched.
- *
- * Return a new URL string to redirect the fetch (e.g., through a proxy),
- * or undefined to use the original URL.
- *
- * @param remoteSrc - The `src` of the remote component being loaded
- * @param url - The asset URL about to be fetched
- *
- * @example
- * // Proxy all assets from the remote's origin through the host
- * const resolveClientUrl = (remoteSrc, url) => {
- *   const remoteOrigin = new URL(remoteSrc).origin;
- *   const parsed = new URL(url);
- *   if (parsed.origin !== location.origin && parsed.origin === remoteOrigin) {
- *     return `/rc-fetch-protected-remote?url=${encodeURIComponent(url)}`;
- *   }
- * };
- */
-type ResolveClientUrl = (remoteSrc: string, url: string) => string | undefined;
-/**
- * Internal bound resolver — `ResolveClientUrl` with `remoteSrc` already applied.
- * Used by internal loaders that don't need to know the remote src.
- */
-type InternalResolveClientUrl = (url: string) => string | undefined;
-
-/**
- * Hook types for intercepting remote component fetch requests and responses.
- *
- * These are part of the public host configuration surface ({@link ConsumeServerConfig})
- * and are used by both SSR and client-side host implementations.
- */
-/**
- * Options object passed to hook functions containing abort capabilities.
- * Uses standard AbortController/AbortSignal for compatibility with Web APIs.
- *
- * @example
- * // Abort on redirect
- * component.onResponse = (url, response, { signal, abort }) => {
- *   if (response.redirected) {
- *     abort();
- *   }
- * };
- *
- * @example
- * // Check if already aborted
- * component.onRequest = (url, init, { signal }) => {
- *   if (signal.aborted) return;
- *   // ...
- * };
- *
- * @example
- * // Pass signal to fetch or other APIs
- * component.onRequest = async (url, init, { signal }) => {
- *   const data = await fetch('/api/check', { signal });
- *   // ...
- * };
- */
-interface HookOptions {
-    /** Standard AbortSignal - can be passed to fetch and other Web APIs */
-    signal: AbortSignal;
-    /** Abort loading - prevents further processing and DOM attachment */
-    abort(reason?: unknown): void;
-}
-/**
- * Hook function that intercepts remote component fetch requests.
- * Can be used to modify request options, provide a custom response, inspect the request,
- * or abort loading.
- *
- * @param url - The URL being fetched
- * @param init - The fetch init options being used
- * @param options - Options object containing the abort signal
- * @returns Optional Response to use instead of fetching, or void/undefined to proceed with normal fetch
- *
- * @example
- * // Log all remote component requests
- * const onRequest = async (url, init, { abort }) => {
- *   console.log('Fetching remote component from:', url.href);
- * };
- *
- * @example
- * // Add custom headers
- * const onRequest = async (url, init) => {
- *   (init.headers as Headers).set('X-Custom-Header', 'value');
- * };
- *
- * @example
- * // Provide a cached response
- * const onRequest = async (url) => {
- *   const cached = cache.get(url.href);
- *   if (cached) {
- *     return new Response(cached);
- *   }
- * };
- *
- * @example
- * // Block certain domains
- * const onRequest = async (url, init, { abort }) => {
- *   if (isBlockedDomain(url)) {
- *     abort('Domain is blocked');
- *   }
- * };
- */
-type OnRequestHook = (url: URL, init: RequestInit, options: HookOptions) => Promise<Response | undefined> | Response | undefined;
-/**
- * Hook function that is called after a remote component fetch completes.
- * Can be used to inspect the response, check for redirects, transform the response,
- * or abort loading.
- *
- * @param url - The original URL that was requested
- * @param response - The Response object from the fetch
- * @param options - Options object containing the abort signal
- * @returns Optional Response to use instead of the original, or void/undefined to use the original response
- *
- * @example
- * // Check for redirects and abort
- * const onResponse = async (url, response, { abort }) => {
- *   if (response.redirected) {
- *     console.log(`Redirected from ${url.href} to ${response.url}`);
- *     abort();
- *   }
- * };
- *
- * @example
- * // Cache the response
- * const onResponse = async (url, response) => {
- *   const cloned = response.clone();
- *   cache.set(url.href, await cloned.text());
- * };
- *
- * @example
- * // Transform the response
- * const onResponse = async (url, response) => {
- *   const text = await response.text();
- *   const modified = text.replace(/foo/g, 'bar');
- *   return new Response(modified, response);
- * };
- *
- * @example
- * // Abort on redirect to legacy routes
- * const onResponse = async (url, response, { abort }) => {
- *   if (response.redirected && isLegacyRoute(response.url)) {
- *     window.location.href = toLegacyUrl(response.url);
- *     abort(); // Abort rendering - no flash!
- *   }
- * };
- */
-type OnResponseHook = (url: URL, response: Response, options: HookOptions) => Promise<Response | undefined> | Response | undefined;
-
-/**
- * Configuration for Shadow DOM isolation of a remote component.
- *
- * Used by both the public {@link ConsumeRemoteComponentConfig} (user-facing props) and
- * {@link ConsumeServerData} (internal runtime data) to control
- * whether and how the remote component is wrapped in a shadow root.
- */
-interface ShadowDomConfig {
-    /** Whether to isolate the remote component using a Shadow DOM wrapper. */
-    isolate?: boolean;
-    /** The Shadow DOM mode. Defaults to `'open'`. */
-    mode?: 'open' | 'closed';
-    /** Whether to include a CSS reset style in the Shadow DOM. Defaults to `false`. */
-    reset?: boolean;
-}
-/**
- * Configuration accepted by server-rendered embed hosts (e.g. the Next.js App Router
- * `<ConsumeRemoteComponent>`). This is the minimal, serializable subset — no client-side
- * asset fetching fields, no lifecycle callbacks.
- *
- * `src` is optional here because not every host has a source at construction
- * time (e.g. the React host during SSR hydration, or a `<remote-component>`
- * element before its `src` attribute is set). Frameworks that require `src`
- * narrow it to required in their own props type.
- */
-interface ConsumeServerConfig extends ShadowDomConfig {
-    /** The source URL of the remote component. Relative or absolute. */
-    src?: string | URL;
-    /** Selects a named remote component when multiple are exposed on a single page. */
-    name?: string;
-    /** Intercepts fetch requests before they are sent. */
-    onRequest?: OnRequestHook;
-    /** Inspects or transforms fetch responses after they arrive. */
-    onResponse?: OnResponseHook;
-}
-/**
- * Client-only configuration fields — the subset of {@link ConsumeClientConfig}
- * that applies only to client-side asset fetching. Used directly in contexts where
- * the full server config is already present (e.g. {@link ConsumeRemoteComponentClient}).
- */
-interface ConsumeClientOnlyConfig {
-    /** The credentials mode for the fetch request. Defaults to `'same-origin'`. */
-    credentials?: RequestCredentials;
-    /**
-     * Rewrites client-side asset URLs (scripts, stylesheets, chunks, modules, images).
-     * Return a new URL string to redirect the request (e.g. through a proxy),
-     * or `undefined` to use the original URL.
-     */
-    resolveClientUrl?: ResolveClientUrl;
-}
-/**
- * Configuration accepted by client-side embed hosts (React host, Pages Router host,
- * HTML host). Extends {@link ConsumeServerConfig} with fields for
- * client-side asset fetching (`credentials`, `resolveClientUrl`).
- */
-interface ConsumeClientConfig extends ConsumeServerConfig, ConsumeClientOnlyConfig {
-}
-/**
- * Complete configuration for client-side embed hosts (React host, Pages Router host).
- * Combines {@link ConsumeClientConfig} with {@link ConsumeLifecycleCallbacks}.
- *
- * This is the base type for public-facing props on hosts that fetch and mount
- * remote components on the client. The App Router server host uses only
- * {@link ConsumeServerConfig} since RSC cannot accept function callbacks.
- */
-interface ConsumeRemoteComponentConfig extends ConsumeClientConfig, ConsumeLifecycleCallbacks {
-}
-/** Information provided to the `onChange` lifecycle callback. */
-interface ChangeInfo {
-    previousSrc: string | URL | null;
-    nextSrc: string | URL | null;
-    previousName: string | undefined;
-    nextName: string | undefined;
-}
-/**
- * Lifecycle callbacks shared by host and remote component implementations.
- *
- * On the host side, these fire during client-side loading (the React host
- * exposes them as callback props; the HTML host dispatches DOM events).
- * On the remote side (Next.js `<ExposeRemoteComponent>` wrapper), the callbacks
- * are forwarded as `data-on-*` attributes so the host can wire them up.
- *
- * Server-only components (e.g. Next.js App Router server host) do not
- * support these callbacks since they render once on the server.
- */
-interface ConsumeLifecycleCallbacks {
-    /** Called right before a new remote component load starts. */
-    onBeforeLoad?: (src: string | URL) => void;
-    /** Called when the remote component has been successfully loaded and mounted. */
-    onLoad?: (src: string | URL) => void;
-    /** Called when an error occurs while loading or mounting the remote component. */
-    onError?: (error: unknown) => void;
-    /** Called when a different remote component is loaded into the same wrapper. */
-    onChange?: (info: ChangeInfo) => void;
-}
-
-/**
- * Metadata embedded in the HTML response by a remote application.
- *
- * Extracted from a `<script type="application/json" data-remote-component>`
- * element during both SSR parsing ({@link fetchRemoteComponent}) and
- * client-side parsing ({@link parseRemoteComponentDocument}).
- */
-interface RemoteComponentMetadata {
-    bundle: string;
-    route: string;
-    runtime: 'webpack' | 'turbopack' | 'script';
-    id: string;
-    type: 'nextjs' | 'remote-component' | 'unknown';
-}
-
-/**
- * Serialized descriptor for a `<script>` element extracted from a remote
- * component response. Used in both SSR fetch results and client-side props.
- */
-interface ScriptDescriptor {
-    /** The script `src` URL. Empty string for inline scripts. */
-    src: string;
-    /** Inline script content (only present for scripts without a `src`). */
-    textContent?: string;
-}
-
-/**
- * The subset of the remote component fetch response that the client-side
- * loader needs to hydrate or mount a remote component.
- *
- * Both {@link ConsumeServerData} and {@link ConsumeLoaderProps}
- * compose this interface — it is the shared base for the RSC→client handoff
- * and the loader function arguments.
- */
-interface ConsumeLoaderPayload {
-    name: string;
-    bundle: string;
-    route?: string;
-    runtime?: RemoteComponentMetadata['runtime'];
-    data: string[];
-    nextData?: {
-        props: {
-            pageProps: Record<string, unknown>;
-        };
-        buildId?: string;
-    } | null;
-    scripts?: ScriptDescriptor[];
-    remoteShared?: Record<string, string>;
-}
-
-/**
- * Props accepted by {@link loadRemoteComponent}.
- *
- * Extends {@link ConsumeLoaderPayload} (the SSR-resolved fields needed for
- * hydration) with loader-specific fields (`url`, `shared`, `container`, etc.).
- * `remoteShared` is narrowed from optional to required (defaults to `{}` at
- * the call site).
- */
-interface ConsumeLoaderProps extends ConsumeLoaderPayload {
-    url: URL;
-    shared: Promise<Record<string, (bundle?: string) => Promise<unknown>>> | Record<string, (bundle?: string) => Promise<unknown>>;
-    remoteShared: Record<string, string>;
-    container?: HTMLHeadElement | ShadowRoot | null;
-    rscName?: string;
-    resolveClientUrl?: InternalResolveClientUrl;
-}
-
-/**
- * Props for the React remote component host.
- *
- * Extends {@link ConsumeRemoteComponentConfig} with `shared` for module sharing and
- * `children` for loading fallback content.
- */
-interface ConsumeRemoteComponentProps extends ConsumeRemoteComponentConfig {
-    /** Shared modules to include in the remote component's context. */
-    shared?: ConsumeLoaderProps['shared'];
-    /** Loading fallback content displayed while the remote component is being fetched. */
-    children?: React.ReactNode;
-}
-/**
- * ConsumeRemoteComponent is a React component that fetches and renders a remote component.
- * It supports SSR and can isolate the remote component in a shadow DOM.
- *
- * @param props - The properties for the remote component.
- * @returns A React component that renders the remote component.
- *
- * @example
- *
- * Use the `<ConsumeRemoteComponent>` in your React application to consume a remote component from a remote application:
- *
- * ```tsx
- * import { ConsumeRemoteComponent } from 'remote-components/host/react';
- *
- * export default function App() {
- *  return (
- *    <>
- *      <h1>Welcome to My App</h1>
- *      <p>This page consumes a remote component from another application.</p>
- *      <ConsumeRemoteComponent src="/nextjs-app-remote/components/header" />
- *    </>
- *  );
- * }
- * ```
- *
- * To share modules, you can provide a shared module map with references to the shared modules:
- *
- * ```tsx
- * <ConsumeRemoteComponent
- *   src="/nextjs-app-remote/components/header"
- *   shared={{
- *     '@/components/provider': () => import('@/components/host-provider')
- *   }}
- * />
- * ```
- */
-declare function ConsumeRemoteComponent({ src, isolate, mode, reset, credentials, name: nameProp, shared, children, onBeforeLoad, onLoad, onError, onChange, onRequest, onResponse, resolveClientUrl: _resolveClientUrl, }: ConsumeRemoteComponentProps): react_jsx_runtime.JSX.Element;
-
-export { ConsumeRemoteComponent, ConsumeRemoteComponentProps, HookOptions, OnRequestHook, OnResponseHook };
+import 'react/jsx-runtime';
+export { b as ConsumeRemoteComponent, a as ConsumeRemoteComponentProps, H as HookOptions, O as OnRequestHook, c as OnResponseHook } from '../index-4c65355c.js';

package/dist/host/react.js

@@ -9,6 +9,7 @@ import {
   useState as useState2
 } from "react";
 import { createPortal } from "react-dom";
+import { useRemoteComponentsContext as useRemoteComponentsContext2 } from "#internal/host/react/context";
 
 // src/utils/constants.ts
 var RC_PROTECTED_REMOTE_FETCH_PATHNAME = "/rc-fetch-protected-remote";
@@ -93,6 +94,11 @@ async function errorFromFailedFetch(originalUrl, resolvedUrl, res) {
   }
   return fallback;
 }
+function failedProxiedAssetError(kind, url, resolvedUrl) {
+  return new RemoteComponentsError(
+    `Failed to load ${kind} "${url}" via proxy "${resolvedUrl}". Ensure withRemoteComponentsHostProxy middleware is configured, "${RC_PROTECTED_REMOTE_FETCH_PATHNAME}" is in the matcher, and the remote URL is included in allowedProxyUrls. See: ${CORS_DOCS_URL}`
+  );
+}
 function failedProxyFetchError(originalUrl, proxyUrl, status, responseBody) {
   if (status === 404) {
     return new RemoteComponentsError(
@@ -144,7 +150,7 @@ function warnCrossOriginFetchError(logLocation, url) {
     }
     logWarn(
       logLocation,
-      `Failed to fetch cross-origin resource "${parsed.href}". If this is a protected deployment, ensure withRemoteComponentsHostProxy middleware is configured in your host and that the remote URL is included in allowedProxyUrls. See: ${CORS_DOCS_URL}`
+      `Failed to fetch cross-origin resource "${parsed.href}". To load assets from a protected deployment, two steps are required: (1) configure withRemoteComponentsHostProxy middleware in your host with the remote URL in allowedProxyUrls, and (2) provide a resolveClientUrl prop that rewrites cross-origin asset URLs to go through the proxy. See: ${CORS_DOCS_URL}`
     );
   } catch {
   }
@@ -657,6 +663,7 @@ import * as ReactDOM from "react-dom";
 import * as ReactDOMClient from "react-dom/client";
 
 // src/config/webpack/apply-shared-modules.ts
+var DEDUPLICATION_SKIPPED = "shared module deduplication skipped. The remote may load its own copy of shared dependencies.";
 function applySharedModules(bundle, resolve) {
   logDebug(
     "SharedModules",
@@ -700,13 +707,16 @@ function applySharedModules(bundle, resolve) {
         } else {
           logWarn(
             "SharedModules",
-            `webpackBundle.m is not available for bundle "${bundle}"`
+            `webpackBundle.m is not available for bundle "${bundle}" \u2014 ${DEDUPLICATION_SKIPPED}`
           );
         }
       }
     }
   } else {
-    logWarn("SharedModules", `No webpack require found for bundle "${bundle}"`);
+    logWarn(
+      "SharedModules",
+      `No webpack require found for bundle "${bundle}" \u2014 ${DEDUPLICATION_SKIPPED}`
+    );
     logDebug(
       "SharedModules",
       `Available bundles: ${Object.keys(self.__remote_webpack_require__ ?? {})}`
@@ -960,11 +970,7 @@ function createChunkLoader(runtime, resolveClientUrl) {
       }).then(resolve).catch((error) => {
         const isProxied = isProxiedUrl(resolvedUrl);
         if (isProxied) {
-          reject(
-            new RemoteComponentsError(
-              `Failed to load chunk "${url}" via proxy "${resolvedUrl}". Ensure withRemoteComponentsHostProxy middleware is configured and "${RC_PROTECTED_REMOTE_FETCH_PATHNAME}" is in the matcher. See: ${CORS_DOCS_URL}`
-            )
-          );
+          reject(failedProxiedAssetError("chunk", url, resolvedUrl));
         } else {
           warnCrossOriginFetchError("ChunkLoader", url);
           reject(error);
@@ -1342,6 +1348,7 @@ function createTurbopackContext(bundle, exports, moduleExports, modules, moduleI
 }
 
 // src/runtime/turbopack/shared-modules.ts
+var DEDUPLICATION_WARNING = "This module will not be deduplicated \u2014 the remote may load its own copy, which can cause duplicate instance errors (e.g. invalid hook calls if React is loaded twice).";
 async function initializeSharedModules(bundle, hostShared = {}, remoteShared = {}) {
   const self = globalThis;
   self.__remote_shared_modules__ = self.__remote_shared_modules__ ?? {};
@@ -1392,7 +1399,7 @@ async function initializeSharedModules(bundle, hostShared = {}, remoteShared = {
             } else {
               logError(
                 "SharedModules",
-                `Host shared module "${module}" not found for ID ${id}`
+                `Host shared module "${module}" not found for ID ${id}. ${DEDUPLICATION_WARNING}`
               );
             }
           }
@@ -1409,7 +1416,7 @@ async function initializeSharedModules(bundle, hostShared = {}, remoteShared = {
         } else {
           logError(
             "SharedModules",
-            `Shared module "${module}" not found for "${bundle}"`
+            `Shared module "${module}" not found for "${bundle}". ${DEDUPLICATION_WARNING}`
           );
         }
       }
@@ -1572,11 +1579,7 @@ async function loadScripts(scripts, resolveClientUrl) {
         newScript.onerror = () => {
           const isProxied = isProxiedUrl(resolvedSrc);
           if (isProxied) {
-            reject(
-              new RemoteComponentsError(
-                `Failed to load script "${newSrc}" via proxy "${resolvedSrc}". Ensure withRemoteComponentsHostProxy middleware is configured and "${RC_PROTECTED_REMOTE_FETCH_PATHNAME}" is in the matcher. See: ${CORS_DOCS_URL}`
-              )
-            );
+            reject(failedProxiedAssetError("script", newSrc, resolvedSrc));
           } else {
             warnCrossOriginFetchError("ScriptLoader", newSrc);
             reject(
@@ -1911,11 +1914,12 @@ function bindResolveClientUrl(prop, remoteSrc) {
 // src/host/react/hooks/use-resolve-client-url.ts
 function useResolveClientUrl(prop, urlHref) {
   const { resolveClientUrl: contextValue } = useRemoteComponentsContext();
-  const resolveClientUrl = prop ?? contextValue;
-  return useMemo(
-    () => bindResolveClientUrl(resolveClientUrl, urlHref),
-    [resolveClientUrl, urlHref]
+  const raw = prop ?? contextValue;
+  const bound = useMemo(
+    () => bindResolveClientUrl(raw, urlHref),
+    [raw, urlHref]
   );
+  return { bound, raw };
 }
 
 // src/host/react/hooks/use-shadow-root.ts
@@ -1997,9 +2001,9 @@ function ConsumeRemoteComponent({
   isolate,
   mode = "open",
   reset,
-  credentials = "same-origin",
+  credentials: credentialsProp,
   name: nameProp = "__vercel_remote_component",
-  shared = {},
+  shared: sharedProp,
   children,
   onBeforeLoad,
   onLoad,
@@ -2007,9 +2011,12 @@ function ConsumeRemoteComponent({
   onChange,
   onRequest,
   onResponse,
-  resolveClientUrl: _resolveClientUrl
+  resolveClientUrl: resolveClientUrlProp
 }) {
   const instanceId = useId();
+  const { credentials: contextCredentials, shared: contextShared } = useRemoteComponentsContext2();
+  const credentials = credentialsProp ?? contextCredentials ?? "same-origin";
+  const shared = sharedProp ?? contextShared ?? {};
   const name = useMemo2(
     () => resolveNameFromSrc(src, nameProp),
     [src, nameProp]
@@ -2018,7 +2025,10 @@ function ConsumeRemoteComponent({
     null
   );
   const url = useMemo2(() => getClientOrServerUrl(src, DUMMY_FALLBACK), [src]);
-  const resolveClientUrl = useResolveClientUrl(_resolveClientUrl, url.href);
+  const { bound: resolveClientUrl } = useResolveClientUrl(
+    resolveClientUrlProp,
+    url.href
+  );
   const id = url.origin === (typeof location !== "undefined" ? location.origin : DUMMY_FALLBACK) ? url.pathname : url.href;
   const keySuffix = `${escapeString(id)}_${escapeString(
     data?.name ?? name