@lwrjs/lwc-ssr 0.11.0-alpha.8 → 0.11.0

package/README.md

@@ -22,6 +22,8 @@
     -   [Debug logging](#debug-logging)
     -   [Breakpoints](#breakpoints)
     -   [Inspect bundles](#inspect-bundles)
+-   [Diagrams](#diagrams)
+    -   [Sequence](#sequence)
 
 ## Overview
 
@@ -136,12 +138,16 @@ type GetServerDataHook = (context: SsrRequestContext) => Promise<SsrDataResponse
 interface SsrRequestContext {
     // props from template attributes
     props: Json;
+    // URL for the request
+    url: string;
     // values from a parameterized route defined in lwr.config.json
     params: { [key: string]: string };
     // search parameters from the request URL
-    query: { [key: string]: string };
+    query: { [key: string]: undefined | string | string[] };
     // locale string for the request, eg: 'en-US'
     locale: string;
+    // base path for the request, eg: '/shop'
+    basePath: string;
 }
 
 interface SsrDataResponse {
@@ -403,3 +409,34 @@ When SSR fails due to a [portability](#portability), it can be difficult to figu
 4. When the problematic code is found, scroll up to find the component to which it belongs.
 
 For example, if SSR fails with this error:`ReferenceError: window is not defined`, then turn off SSR and search the module bundles for prohibited usages of the `window` object.
+
+## Diagrams
+
+### Sequence
+
+```mermaid
+sequenceDiagram
+%% SSR with Data
+    actor client as Client
+    box LWR-Node
+        participant registry as View Registry
+        participant transformer as SSR View<br>Transformer
+        participant sandbox as SSR Sandbox
+    end
+    client ->> registry: Requests a page
+    registry ->> registry: Generates an HTML base document from layout and content templates
+    registry ->> transformer: Sends the base document to get islands processed
+    loop For each non-client-only island
+        transformer ->> sandbox: Sends the island to be SSRed
+        sandbox ->> sandbox: Runs the component's getServerData hook
+        sandbox ->> sandbox: Runs the route's SSR bootstrap services
+        sandbox ->> sandbox: Converts the island to HTML via LWC SSR
+        sandbox ->> transformer: Returns the HTML for the island
+        transformer ->> transformer: Replaces the island's HTML element with its SSRed HTML
+    end
+    transformer -->> registry: Return
+    registry ->> registry: Serializes the serverData into the base document
+    registry -->> client: Responds with the base document
+    client ->> client: Runs the route's SSR bootstrap services
+    client ->> client: Hydrates SSRed islands with serialized serverData
+```

package/build/cjs/moduleProvider/index.cjs

@@ -28,38 +28,68 @@ __export(exports, {
   default: () => moduleProvider_default
 });
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
+var import_instrumentation = __toModule(require("@lwrjs/instrumentation"));
 var import_identity = __toModule(require("../identity.cjs"));
 function createSsrBootstrapModule(rootSpecifier, services) {
   let serviceImports = "";
   let serviceCalls = "";
   services.forEach((service) => {
-    const importName = `service_${service.replace(/\//gi, "_").replace(/@/gi, "")}`;
+    const importName = (0, import_shared_utils.stringToVariableName)(`service_${service}`);
     serviceImports += `
 import ${importName} from '${service}';`;
     serviceCalls += `
-${importName}();`;
+
+        globalThis.trace({
+            name: '${import_instrumentation.ViewSpan.BootstrapService}',
+            attributes: {
+                specifier: '${rootSpecifier}',
+                serviceSpecifier: '${service}',
+            }
+        }, () => {
+            try {
+                ${importName}({ serverData });
+            } catch(e) {
+                const message = e.message || e;
+                // we need to re-throw with the service specifier in the error message
+                throw new Error('An SSR error occurred in bootstrap service "${service}": ' + message);
+            }
+        });`;
   });
   return `
 import { renderComponent } from '@lwc/engine-server';
 import Ctor, * as rootComponent from '${rootSpecifier}';${serviceImports}
 
 (async () => {
-    let result, props, markup, existingTaskCount;
+    let result, props, markup, serverData = globalThis.LWR?.serverData || {}, existingTaskCount;
+    // remove the LWR global properties before any customer code is run
+    if (globalThis.LWR?.define) {
+        // AMD: support dynamic imports in getServerData
+        globalThis.LWR = Object.freeze({ define: globalThis.LWR.define });
+    } else {
+        delete globalThis.LWR; // ESM
+    }
+
     try {
         // 1. setup page data
         const context = globalThis.getContext();
         props = context.props;
         if (rootComponent.getServerData) {
             const data = await globalThis.trace({
-                name: 'lwr.view.getServerData',
+                name: '${import_instrumentation.ViewSpan.GetServerData}',
                 attributes: {
                     specifier: '${rootSpecifier}'
                 }
-            }, () => rootComponent.getServerData(context));
-
+            }, async() => {
+                try {
+                    return await rootComponent.getServerData(context)
+                } catch(e) {
+                    const message = e.message || e;
+                    // we need to re-throw with rootSpecifier in the error message
+                    throw new Error('Error in "getServerData" for "${rootSpecifier}": ' + message);
+                }
+            });
             props = data.props; // overwrite public props
-            globalThis.LWR = globalThis.LWR || { serverData: {} };
-            Object.assign(globalThis.LWR.serverData, data.props); // add props to server data
+            Object.assign(serverData, data.props); // add props to server data
             markup = data.markup;
         }${serviceCalls}
 
@@ -69,7 +99,7 @@ import Ctor, * as rootComponent from '${rootSpecifier}';${serviceImports}
 
         // 2. render component
         result = globalThis.trace({
-            name: 'lwr.view.renderComponent',
+            name: '${import_instrumentation.ViewSpan.RenderComponent}',
             attributes: {
                 specifier: '${rootSpecifier}'
             }
@@ -77,8 +107,8 @@ import Ctor, * as rootComponent from '${rootSpecifier}';${serviceImports}
 
     } catch(e) {
         const message = e.message || e;
-        // Relay the LWC rendering stack
-        
+
+        // add the LWC rendering stack
         const error = e.wcStack ? 
         'An error occurred during server-side rendering for component stack: ' + e.wcStack + '. Error was: ' + message :
         'An error occured during server-side rendering: ' + message;
@@ -90,7 +120,6 @@ import Ctor, * as rootComponent from '${rootSpecifier}';${serviceImports}
     const currentTaskCount = process.getActiveResourcesInfo
             ? process.getActiveResourcesInfo().length
             : 0;
-
     if (currentTaskCount - existingTaskCount > 0) {
         console.warn('[warn] async tasks encountered while server rendering "${rootSpecifier}"');
     }

package/build/cjs/utils/amd-utils.cjs

@@ -92,7 +92,7 @@ async function getCode(runtimeEnvironment, serverData, lwrVersion, bundleSpecifi
 }
 async function getBundle(specifier, moduleBundler, routes, runtimeEnvironment, runtimeParams) {
   if ((0, import_shared_utils.getFeatureFlags)().SSR_STATIC_BUNDLES) {
-    return buildBundle(specifier, moduleBundler, routes, runtimeEnvironment, runtimeParams);
+    return buildBundle(specifier, moduleBundler, routes, {...runtimeEnvironment, debug: false}, runtimeParams);
   }
   return bundle(specifier, moduleBundler, runtimeEnvironment, runtimeParams, {
     appendExcludes: false,
@@ -102,27 +102,38 @@ async function getBundle(specifier, moduleBundler, routes, runtimeEnvironment, r
 async function bundle(specifier, moduleBundler, runtimeEnvironment, runtimeParams, bundleConfigOverrides) {
   return await moduleBundler.getModuleBundle({specifier}, runtimeEnvironment, runtimeParams, bundleConfigOverrides);
 }
-async function bundleImports(bundleCode, imports = [], visited, moduleBundler, runtimeEnvironment, runtimeParams) {
+async function bundleImports(bundleCode, dynamicImports = [], imports = [], visited, moduleBundler, runtimeEnvironment, runtimeParams) {
   for (const {specifier} of imports) {
     if (!visited.has(specifier)) {
       visited.add(specifier);
       const {code, bundleRecord, version} = await bundle(specifier, moduleBundler, runtimeEnvironment, runtimeParams);
-      let bundledCode;
-      if (runtimeEnvironment.featureFlags?.EXPERIMENTAL_UNVERSIONED_ALIASES) {
-        const versionedSpecifier = (0, import_shared_utils.getSpecifier)({specifier, version});
-        const aliasCode = (0, import_shared_utils.createAmdAlias)(versionedSpecifier, specifier);
-        bundledCode = [code, aliasCode].filter(Boolean).join("");
-      } else {
-        bundledCode = code;
-      }
-      bundleCode = await bundleImports(bundledCode, bundleRecord.imports, visited, moduleBundler, runtimeEnvironment, runtimeParams) + bundleCode;
+      const bundledCode = getBundledCode(runtimeEnvironment, specifier, version, code);
+      bundleCode = await bundleImports(bundledCode, bundleRecord.dynamicImports, bundleRecord.imports, visited, moduleBundler, runtimeEnvironment, runtimeParams) + bundleCode;
+    }
+  }
+  for (const {specifier} of dynamicImports) {
+    if (!visited.has(specifier)) {
+      visited.add(specifier);
+      const {code, version} = await bundle(specifier, moduleBundler, runtimeEnvironment, runtimeParams);
+      bundleCode += getBundledCode(runtimeEnvironment, specifier, version, code);
     }
   }
   return bundleCode;
 }
+function getBundledCode(runtimeEnvironment, specifier, version, code) {
+  let bundledCode;
+  if (runtimeEnvironment.featureFlags?.EXPERIMENTAL_UNVERSIONED_ALIASES) {
+    const versionedSpecifier = (0, import_shared_utils.getSpecifier)({specifier, version});
+    const aliasCode = (0, import_shared_utils.createAmdAlias)(versionedSpecifier, specifier);
+    bundledCode = [code, aliasCode].filter(Boolean).join("");
+  } else {
+    bundledCode = code;
+  }
+  return bundledCode;
+}
 async function getBundleWithImports(specifier, moduleBundler, runtimeEnvironment, runtimeParams) {
   const {code, bundleRecord} = await bundle(specifier, moduleBundler, runtimeEnvironment, runtimeParams);
-  return await bundleImports(code, bundleRecord.imports, new Set(["lwc", specifier]), moduleBundler, runtimeEnvironment, runtimeParams);
+  return await bundleImports(code, bundleRecord.dynamicImports, bundleRecord.imports, new Set(["lwc", specifier]), moduleBundler, runtimeEnvironment, runtimeParams);
 }
 async function buildBundle(ssrSpecifier, moduleBundler, routes, runtimeEnvironment, runtimeParams) {
   const {rootSpecifier, route} = (0, import_identity.parseSpecifier)(ssrSpecifier, routes);

package/build/cjs/utils/sandbox-locker.cjs

@@ -28,11 +28,10 @@ __export(exports, {
 });
 var import_instrumentation = __toModule(require("@lwrjs/instrumentation"));
 var import_near_membrane_node = __toModule(require("@locker/near-membrane-node"));
-var import_node_fetch = __toModule(require("node-fetch"));
 var import_crypto = __toModule(require("crypto"));
 var import_url = __toModule(require("url"));
 var import_utils = __toModule(require("./utils.cjs"));
-function runCode(codes, context) {
+function runCode(codes, context, host) {
   return new Promise((resolve, reject) => {
     let resolver;
     const p = new Promise((r) => resolver = r);
@@ -46,9 +45,10 @@ function runCode(codes, context) {
       crypto: import_crypto.webcrypto,
       getContext,
       trace,
-      fetch: import_node_fetch.default,
+      fetch: (0, import_utils.createFetchEndowment)(host),
       resolver,
       URL: import_url.URL,
+      URLSearchParams: import_url.URLSearchParams,
       process,
       setTimeout,
       clearTimeout,

package/build/cjs/utils/sandbox-worker.cjs

@@ -31,17 +31,18 @@ var import_utils = __toModule(require("./utils.cjs"));
 var HEADER = "/* This module is generated and meant to be used in a Server context */";
 var WORKER_CODE_SANDBOX_APIS = [
   `const { parentPort, workerData } = require('worker_threads');`,
+  `globalThis.fetch = require('@lwrjs/lwc-ssr/viewTransformer').createFetchEndowment(workerData.host);`,
+  `delete workerData.host`,
   `globalThis.getContext = () => workerData;`,
-  `globalThis.fetch = require('node-fetch');`,
   `globalThis.crypto = require('crypto').webcrypto;`,
   `globalThis.resolver = (...args) => parentPort.postMessage(...args);`,
   `globalThis.trace = (id, fn) => fn()`
 ];
-function runCode(codes, workerData) {
+function runCode(codes, workerData, host) {
   const time = (0, import_utils.getWatchdogTime)();
   const workerCode = [HEADER, ...WORKER_CODE_SANDBOX_APIS, ...codes].join("\n");
   return new Promise((resolve, reject) => {
-    const worker = new import_worker_threads.Worker(workerCode, {eval: true, workerData});
+    const worker = new import_worker_threads.Worker(workerCode, {eval: true, workerData: {...workerData, host}});
     const timerId = (0, import_utils.startWatchdogTimer)(() => {
       worker.terminate();
       reject(new Error(`SSR timed out after ${time}ms`));

package/build/cjs/utils/sandbox.cjs

@@ -29,9 +29,9 @@ __export(exports, {
 var import_sandbox_worker = __toModule(require("./sandbox-worker.cjs"));
 var import_sandbox_locker = __toModule(require("./sandbox-locker.cjs"));
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
-function runCode(codes, context) {
+function runCode(codes, context, host) {
   if ((0, import_shared_utils.getFeatureFlags)().SSR_SANDBOX_WORKER) {
-    return (0, import_sandbox_worker.default)(codes, context);
+    return (0, import_sandbox_worker.default)(codes, context, host);
   }
-  return (0, import_sandbox_locker.default)(codes, context);
+  return (0, import_sandbox_locker.default)(codes, context, host);
 }

package/build/cjs/utils/ssr-element.cjs

@@ -29,9 +29,9 @@ __export(exports, {
 var import_amd_utils = __toModule(require("./amd-utils.cjs"));
 var import_sandbox = __toModule(require("./sandbox.cjs"));
 var import_perf_hooks = __toModule(require("perf_hooks"));
-var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
+var import_diagnostics = __toModule(require("@lwrjs/diagnostics"));
 var import_instrumentation = __toModule(require("@lwrjs/instrumentation"));
-var SSR_FLAG = "process.env.SSR = true;";
+var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
 var EMIT_WIRES = `globalThis.lwcRuntimeFlags = { ENABLE_WIRE_SYNC_EMIT: true };`;
 async function ssrElement({
   specifier,
@@ -52,10 +52,18 @@ async function ssrElement({
   }) : await (0, import_amd_utils.getBundle)(specifier, moduleBundler, routes, runtimeEnvironment, runtimeParams);
   const context = {
     props: templateProps,
+    url: runtimeParams.url,
     params: runtimeParams.params || {},
     query: runtimeParams.query || {},
-    locale: runtimeParams.locale || runtimeEnvironment.defaultLocale
+    locale: runtimeParams.locale || runtimeEnvironment.i18n.defaultLocale,
+    basePath: runtimeParams.basePath || runtimeEnvironment.basePath
+  };
+  const environment = {
+    SSR: true,
+    ...(0, import_shared_utils.buildEnvironmentContext)(runtimeParams)
   };
+  const environmentCode = `process.env = ${JSON.stringify(environment)}`;
+  const host = runtimeParams.host;
   const startTime = import_perf_hooks.performance.now();
   return (0, import_instrumentation.getTracer)().trace({
     name: import_instrumentation.ViewSpan.ServerSideRender,
@@ -64,14 +72,14 @@ async function ssrElement({
     }
   }, async () => {
     const {result, props, markup, cache, error} = format === "amd" ? await (0, import_sandbox.default)([
-      SSR_FLAG,
       EMIT_WIRES,
+      environmentCode,
       ...await (0, import_amd_utils.getCode)(runtimeEnvironment, serverData, version.replace(/\./g, "_"), bundleSpecifier, bundleRecord.includedModules, resourceRegistry),
       code
-    ], context) : await (0, import_sandbox.default)([SSR_FLAG, EMIT_WIRES, code], context);
+    ], context, host) : await (0, import_sandbox.default)([EMIT_WIRES, environmentCode, code], context, host);
     const endTime = import_perf_hooks.performance.now();
     const timeDiff = endTime - startTime;
-    import_shared_utils.logger.info(`[Server-side Rendering] ${specifier} in ${Math.round(timeDiff)} ms`);
+    import_diagnostics.logger.info(`[Server-side Rendering] ${specifier} in ${Math.round(timeDiff)} ms`);
     if (error)
       throw new Error(error);
     return {html: result, props, markup, cache};

package/build/cjs/utils/utils.cjs

@@ -1,17 +1,36 @@
+var __create = Object.create;
 var __defProp = Object.defineProperty;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __markAsModule = (target) => __defProp(target, "__esModule", {value: true});
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {get: all[name], enumerable: true});
 };
+var __exportStar = (target, module2, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && key !== "default")
+        __defProp(target, key, {get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable});
+  }
+  return target;
+};
+var __toModule = (module2) => {
+  return __exportStar(__markAsModule(__defProp(module2 != null ? __create(__getProtoOf(module2)) : {}, "default", module2 && module2.__esModule && "default" in module2 ? {get: () => module2.default, enumerable: true} : {value: module2, enumerable: true})), module2);
+};
 
 // packages/@lwrjs/lwc-ssr/src/utils/utils.ts
 __markAsModule(exports);
 __export(exports, {
+  createFetchEndowment: () => createFetchEndowment,
+  createSsrErrorMessage: () => createSsrErrorMessage,
   getWatchdogTime: () => getWatchdogTime,
   startWatchdogTimer: () => startWatchdogTimer,
   stopWatchdogTimer: () => stopWatchdogTimer
 });
+var import_node_fetch = __toModule(require("node-fetch"));
 var DEFAULT_SSR_TIMEOUT = 5e3;
 function getWatchdogTime() {
   const override = process.env.SSR_TIMEOUT;
@@ -23,3 +42,18 @@ function startWatchdogTimer(callback, time) {
 function stopWatchdogTimer(timerId) {
   clearTimeout(timerId);
 }
+function createFetchEndowment(host) {
+  if (!host) {
+    return import_node_fetch.default;
+  }
+  return (url, init) => {
+    const urlStr = typeof url === "string" ? url : url.toString();
+    if (urlStr.startsWith("/")) {
+      return (0, import_node_fetch.default)(host + url, init);
+    }
+    return (0, import_node_fetch.default)(url, init);
+  };
+}
+function createSsrErrorMessage(specifier, e) {
+  return `Server-side rendering for "${specifier}" failed. Falling back to client-side rendering. Reason: ${e.message || e}`;
+}

package/build/cjs/viewProvider/index.cjs

@@ -27,9 +27,12 @@ __export(exports, {
   default: () => viewProvider_default
 });
 var import_base_view_provider = __toModule(require("@lwrjs/base-view-provider"));
+var import_diagnostics = __toModule(require("@lwrjs/diagnostics"));
+var import_instrumentation = __toModule(require("@lwrjs/instrumentation"));
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
 var import_identity = __toModule(require("../identity.cjs"));
 var import_ssr_element = __toModule(require("../utils/ssr-element.cjs"));
+var import_utils = __toModule(require("../utils/utils.cjs"));
 var LwcViewProvider = class extends import_base_view_provider.default {
   constructor(pluginConfig, providerConfig) {
     super();
@@ -42,13 +45,11 @@ var LwcViewProvider = class extends import_base_view_provider.default {
   async initialize() {
     return;
   }
-  async getView(viewId, runtimeParams = {}) {
+  async getView(viewId) {
     const specifier = viewId.contentTemplate?.component;
     if (!specifier || !(0, import_shared_utils.isSpecifier)(specifier)) {
       return;
     }
-    const {moduleBundler, resourceRegistry, runtimeEnvironment} = this;
-    const {html: renderedView, props} = await (0, import_ssr_element.ssrElement)({specifier: `${import_identity.LWC_SSR_PREFIX}${viewId.id}/${specifier}`, props: {}}, moduleBundler, resourceRegistry, this.routes, {runtimeEnvironment, runtimeParams});
     return {
       name: specifier,
       slug: (0, import_shared_utils.slugify)(specifier),
@@ -56,10 +57,41 @@ var LwcViewProvider = class extends import_base_view_provider.default {
       originalSource: specifier,
       filePath: specifier,
       viewId,
-      render: async () => ({
-        renderedView,
-        metadata: {serverData: props, customElements: [], assetReferences: []}
-      })
+      render: async (runtimeParams) => {
+        const {moduleBundler, resourceRegistry, runtimeEnvironment} = this;
+        const debug = runtimeParams.query?.debug !== void 0;
+        const element = (0, import_shared_utils.moduleSpecifierToKebabCase)(specifier);
+        return (0, import_instrumentation.getTracer)().trace({
+          name: import_instrumentation.ViewSpan.RenderPage,
+          attributes: {specifier}
+        }, async () => {
+          try {
+            const {html, props} = await (0, import_ssr_element.ssrElement)({specifier: `${import_identity.LWC_SSR_PREFIX}${viewId.id}/${specifier}`, props: {}}, moduleBundler, resourceRegistry, this.routes, {
+              runtimeEnvironment: {...runtimeEnvironment, debug},
+              runtimeParams
+            });
+            return {
+              renderedView: html.replace(`<${element}`, `<${element} lwc:external`),
+              metadata: {serverData: props, customElements: [], assetReferences: []}
+            };
+          } catch (e) {
+            if (debug || (0, import_shared_utils.getFeatureFlags)().SSR_WITH_CSR_FALLBACK) {
+              const message = (0, import_utils.createSsrErrorMessage)(specifier, e);
+              import_diagnostics.logger.warn(message, e.stack);
+              return {
+                renderedView: `<${element} ${import_shared_utils.HYDRATE_DIRECTIVE}="${import_shared_utils.HYDRATE_CLIENT_VALUE}"></${element}>`,
+                metadata: {
+                  serverDebug: {message: debug ? message : void 0},
+                  customElements: [],
+                  assetReferences: []
+                }
+              };
+            } else {
+              throw e;
+            }
+          }
+        });
+      }
     };
   }
 };

package/build/cjs/viewTransformer/index.cjs

@@ -24,25 +24,34 @@ var __toModule = (module2) => {
 // packages/@lwrjs/lwc-ssr/src/viewTransformer/index.ts
 __markAsModule(exports);
 __export(exports, {
+  createFetchEndowment: () => import_utils2.createFetchEndowment,
   default: () => lwcSsrViewTransformer
 });
+var import_diagnostics = __toModule(require("@lwrjs/diagnostics"));
+var import_instrumentation = __toModule(require("@lwrjs/instrumentation"));
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
 var import_identity = __toModule(require("../identity.cjs"));
 var import_ssr_element = __toModule(require("../utils/ssr-element.cjs"));
+var import_utils = __toModule(require("../utils/utils.cjs"));
+var import_utils2 = __toModule(require("../utils/utils.cjs"));
 function lwcSsrViewTransformer(options, {config, moduleBundler, resourceRegistry}) {
   const routes = [...config.routes, ...config.errorRoutes];
   return {
     name: "ssr-lwc-transformer",
     async link(stringBuilder, viewContext, metadata) {
+      const {debug} = viewContext.runtimeEnvironment;
       if (!viewContext.view.bootstrap?.ssr) {
         return {};
       }
-      import_shared_utils.logger.debug("[lwcSsrViewTransformer] link");
-      import_shared_utils.logger.verbose("[lwcSsrViewTransformer] link input", stringBuilder);
+      import_diagnostics.logger.debug("[lwcSsrViewTransformer] link");
+      import_diagnostics.logger.verbose("[lwcSsrViewTransformer] link input", stringBuilder);
       if (!metadata.serverData) {
         metadata.serverData = {};
       }
-      const {customElements, serverData} = metadata;
+      if (!metadata.serverDebug) {
+        metadata.serverDebug = {};
+      }
+      const {customElements, serverData, serverDebug} = metadata;
       const ssrModules = [];
       for (const [index, {tagName, location, props}] of customElements.entries()) {
         const isCsr = (0, import_shared_utils.isCsrIsland)(props);
@@ -50,7 +59,7 @@ function lwcSsrViewTransformer(options, {config, moduleBundler, resourceRegistry
           const {startOffset, endOffset} = location;
           stringBuilder.overwrite(startOffset, endOffset, `<${tagName}></${tagName}>`);
         }
-        if (!isCsr && location) {
+        if (!isCsr && !props?.["lwc:external"] && location) {
           const {startOffset, endOffset} = location;
           const moduleSpecifier = (0, import_shared_utils.kebabCaseToModuleSpecifier)(tagName);
           ssrModules.push({
@@ -59,46 +68,64 @@ function lwcSsrViewTransformer(options, {config, moduleBundler, resourceRegistry
             endOffset,
             props,
             tagName,
-            specifier: `${import_identity.LWC_SSR_PREFIX}${viewContext.view.id}/${moduleSpecifier}`
+            bootstrapSpecifier: `${import_identity.LWC_SSR_PREFIX}${viewContext.view.id}/${moduleSpecifier}`,
+            specifier: moduleSpecifier
           });
         }
       }
-      let ssrLinks = "";
-      let pageTtl;
-      await Promise.all(ssrModules.map(({index, specifier, tagName, props: rawProps = {}, startOffset, endOffset}) => {
+      let ssrLinks = "", pageTtl, debugMessage;
+      await Promise.all(ssrModules.map(({
+        index,
+        bootstrapSpecifier,
+        specifier,
+        tagName,
+        props: rawProps = {},
+        startOffset,
+        endOffset
+      }) => {
         const hydrate = (0, import_shared_utils.isHydrateOnLoad)(rawProps);
         const passProps = {...rawProps};
         delete passProps[import_shared_utils.HYDRATE_DIRECTIVE];
-        return (0, import_ssr_element.ssrElement)({specifier, props: passProps, serverData}, moduleBundler, resourceRegistry, routes, viewContext).then(({
-          html,
-          props = {},
-          markup: {links = []} = {links: []},
-          cache: {ttl} = {}
-        }) => {
-          pageTtl = (0, import_shared_utils.shortestTtl)(ttl, pageTtl);
-          let propsAttr = "";
-          if (hydrate) {
-            const propsId = (0, import_identity.getPropsId)();
-            propsAttr = ` ${import_identity.SSR_PROPS_ATTR}="${propsId}"`;
-            serverData[propsId] = props;
-          }
-          const [, remain] = html.split(`<${tagName}`);
-          html = [`<${tagName}`, propsAttr, remain].join("");
-          links.forEach(({href, rel, as, fetchpriority}) => {
-            const relStr = rel ? ` rel="${rel}"` : "", asStr = as ? ` as="${as}"` : "", fetchStr = fetchpriority ? ` fetchpriority="${fetchpriority}"` : "";
-            ssrLinks += `<link href="${href}"${relStr}${asStr}${fetchStr}>
+        return (0, import_instrumentation.getTracer)().trace({
+          name: import_instrumentation.ViewSpan.RenderIsland,
+          attributes: {specifier}
+        }, async () => {
+          return (0, import_ssr_element.ssrElement)({specifier: bootstrapSpecifier, props: passProps, serverData}, moduleBundler, resourceRegistry, routes, viewContext).then(({
+            html,
+            props = {},
+            markup: {links = []} = {links: []},
+            cache: {ttl} = {}
+          }) => {
+            pageTtl = (0, import_shared_utils.shortestTtl)(ttl, pageTtl);
+            let propsAttr = "";
+            if (hydrate) {
+              const propsId = (0, import_identity.getPropsId)();
+              propsAttr = ` ${import_identity.SSR_PROPS_ATTR}="${propsId}"`;
+              serverData[propsId] = props;
+            }
+            const [, remain] = html.split(`<${tagName}`);
+            html = [`<${tagName}`, propsAttr, remain].join("");
+            links.forEach(({href, rel, as, fetchpriority}) => {
+              const relStr = rel ? ` rel="${rel}"` : "", asStr = as ? ` as="${as}"` : "", fetchStr = fetchpriority ? ` fetchpriority="${fetchpriority}"` : "";
+              ssrLinks += `<link href="${href}"${relStr}${asStr}${fetchStr}>
 `;
+            });
+            stringBuilder.overwrite(startOffset, endOffset, html);
+          }).catch((err) => {
+            if (debug || (0, import_shared_utils.getFeatureFlags)().SSR_WITH_CSR_FALLBACK) {
+              customElements[index].props === void 0 ? customElements[index].props = {
+                [import_shared_utils.HYDRATE_DIRECTIVE]: import_shared_utils.HYDRATE_CLIENT_VALUE
+              } : customElements[index].props[import_shared_utils.HYDRATE_DIRECTIVE] = import_shared_utils.HYDRATE_CLIENT_VALUE;
+              const errMessage = (0, import_utils.createSsrErrorMessage)(specifier, err);
+              import_diagnostics.logger.warn(errMessage, err.stack);
+              if (debug) {
+                debugMessage = errMessage;
+                serverDebug.message = debugMessage;
+              }
+            } else {
+              throw err;
+            }
           });
-          stringBuilder.overwrite(startOffset, endOffset, html);
-        }).catch((err) => {
-          if ((0, import_shared_utils.getFeatureFlags)().SSR_WITH_CSR_FALLBACK) {
-            customElements[index].props === void 0 ? customElements[index].props = {
-              [import_shared_utils.HYDRATE_DIRECTIVE]: import_shared_utils.HYDRATE_CLIENT_VALUE
-            } : customElements[index].props[import_shared_utils.HYDRATE_DIRECTIVE] = import_shared_utils.HYDRATE_CLIENT_VALUE;
-            import_shared_utils.logger.warn(`Server-side rendering for "${specifier}" failed. Falling back to client-side rendering. Reason: `, err.stack);
-          } else {
-            throw err;
-          }
         });
       }));
       if (ssrLinks) {
@@ -106,10 +133,10 @@ function lwcSsrViewTransformer(options, {config, moduleBundler, resourceRegistry
         if (headIndex >= 0) {
           stringBuilder.prependLeft(headIndex, ssrLinks);
         } else {
-          import_shared_utils.logger.error("Adding links during server-side rendering failed. Could not find the </head> tag.");
+          import_diagnostics.logger.error("Adding links during server-side rendering failed. Could not find the </head> tag.");
         }
       }
-      import_shared_utils.logger.verbose("lwcSsrViewTransformer response", stringBuilder);
+      import_diagnostics.logger.verbose("lwcSsrViewTransformer response", stringBuilder);
       return {cache: {ttl: pageTtl}};
     }
   };