feat: support external esm module scripts

Author: markacianfrani

sandpack-client/src/clients/runtime/types.ts

@@ -11,6 +11,7 @@ import type {
   SandpackErrorMessage,
   SandpackLogLevel,
   SandpackMessageConsoleMethods,
+  ExternalScriptResource
 } from "../..";
 
 export type SandpackRuntimeMessage = BaseSandpackMessage &
@@ -66,7 +67,7 @@ export type SandpackRuntimeMessage = BaseSandpackMessage &
         version: number;
         isInitializationCompile?: boolean;
         modules: Modules;
-        externalResources: string[];
+        externalResources?: Array<string | ExternalScriptResource>;
         hasFileResolver: boolean;
         disableDependencyPreprocessing?: boolean;
         template?: string | ITemplate;

sandpack-client/src/clients/static/index.ts

@@ -5,6 +5,7 @@ import { PreviewController } from "static-browser-server";
 
 import type {
   ClientOptions,
+  ExternalScriptResource,
   ListenerFunction,
   SandboxSetup,
   UnsubscribeFunction,
@@ -132,26 +133,37 @@ export class SandpackStatic extends SandpackClient {
   ): FileContent {
     const tagsToInsert = externalResources
       .map((resource) => {
-        const match = resource.match(/\.([^.]*)$/);
-        const fileType = match?.[1];
-
-        if (fileType === "css" || resource.includes("fonts.googleapis")) {
-          return `<link rel="stylesheet" href="${resource}">`;
-        }
-
-        if (fileType === "js") {
-          return `<script src="${resource}"></script>`;
+        if (this.isScriptResource(resource)) {
+          return `<script type="${resource.type}" src="${resource.src}"></script>`;
+        } else {
+          const match = resource.match(/\.([^.]*)$/);
+          const fileType = match?.[1];
+  
+          if (fileType === "css" || resource.includes("fonts.googleapis")) {
+            return `<link rel="stylesheet" href="${resource}">`;
+          }
+  
+          if (fileType === "js") {
+            return `<script src="${resource}"></script>`;
+          }
+  
+          throw new Error(
+            `Unable to determine file type for external resource: ${resource}`
+          );
         }
-
-        throw new Error(
-          `Unable to determine file type for external resource: ${resource}`
-        );
       })
       .join("\n");
 
     return this.injectContentIntoHead(content, tagsToInsert);
   }
 
+  private isScriptResource(resource: unknown): resource is ExternalScriptResource {
+    return typeof resource === 'object' 
+      && resource !== null 
+      && 'type' in resource 
+      && 'src' in resource;
+  }
+
   private injectScriptIntoHead(
     content: FileContent,
     opts: {

sandpack-client/src/types.ts

@@ -5,7 +5,7 @@ export interface ClientOptions {
   /**
    * Paths to external resources
    */
-  externalResources?: string[];
+  externalResources?: Array<string | ExternalScriptResource>;
   /**
    * Location of the bundler.
    */
@@ -72,6 +72,11 @@ export interface ClientOptions {
   teamId?: string;
 }
 
+export interface ExternalScriptResource {
+  type: "module" | "importmap" | undefined;
+  src: string;
+}
+
 export interface SandboxSetup {
   files: SandpackBundlerFiles;
   dependencies?: Dependencies;

sandpack-react/src/types.ts

@@ -12,6 +12,7 @@ import type {
   UnsubscribeFunction,
   SandpackLogLevel,
   NpmRegistry,
+  ExternalScriptResource
 } from "@codesandbox/sandpack-client";
 import type React from "react";
 
@@ -171,7 +172,8 @@ export interface SandpackOptions {
   startRoute?: string;
   skipEval?: boolean;
   fileResolver?: FileResolver;
-  externalResources?: string[];
+  
+  externalResources?: Array<string | ExternalScriptResource>;
 }
 
 /**
@@ -460,7 +462,7 @@ export interface SandpackInternalOptions<
   startRoute?: string;
   skipEval?: boolean;
   fileResolver?: FileResolver;
-  externalResources?: string[];
+  externalResources?: Array<string | ExternalScriptResource>;
   classes?: Record<string, string>;
 }
 

website/docs/src/pages/advanced-usage/client.mdx

@@ -291,7 +291,7 @@ The `getCodeSandboxURL` method creates a sandbox from the current files and retu
   /**
    * Paths to external resources
    */
-  externalResources?: string[];
+  externalResources?: Array<string | ExternalScriptResource>;
   /**
    * Location of the bundler. Defaults to `${version}-sandpack.codesandbox.io`
    */