Fix issues with copydecks not being loadable in browsers / React

Author: grega

README.md

@@ -3,6 +3,7 @@
 - [ ] Ensure all strings in `src/` are localised
 - [ ] Consider renaming `explain()` to something like `friendlyExplain()`?
 - [ ] Figure out where the built packages should live / be served from
+  - [ ] Set up automated publishing through GitHub Actions
 - [ ] BEM-style formatting for CSS classes?
 - [ ] Open source?
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raspberrypifoundation/python-friendly-error-messages",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -22,7 +22,7 @@
     "clean": "rimraf dist",
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
-    "build:browser": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.browser.js",
+    "build:browser": "esbuild src/index.browser.ts --bundle --format=esm --outfile=dist/index.browser.js --loader:.json=json",
     "build:assets": "mkdir -p dist/copydecks && cp -R copydecks/* dist/copydecks/",
     "build:all": "npm run build && npm run build:browser && npm run build:assets",
     "test": "vitest run",

src/index.browser.ts

@@ -0,0 +1,6 @@
+export type { Trace, ExplainOptions, ExplainResult, CopyDeck, AdapterFn } from "./types.js";
+export { loadCopydeck, registerAdapter, explain } from "./engine.js";
+export { skulptAdapter } from "./adapters/skulpt.js";
+export { pyodideAdapter } from "./adapters/pyodide.js";
+export { loadCopydeckFor } from "./loaders.browser.js";
+

src/loaders.browser.ts

@@ -0,0 +1,45 @@
+import { loadCopydeck } from "./engine.js";
+import type { CopyDeck } from "./types.js";
+import enCopydeck from "../copydecks/en/copydeck.json";
+
+// is this the best way to do this when we come to adding more languages / copydecks?
+const bundledCopydecks: Record<string, CopyDeck> = {
+  en: enCopydeck as CopyDeck,
+};
+
+type Options = { base?: string };
+
+export async function loadCopydeckFor(locale = "en", opts: Options = {}): Promise<CopyDeck> {
+  const tryLocales = [locale];
+  const baseLang = locale.split("-")[0];
+  if (baseLang !== locale) tryLocales.push(baseLang);
+  if (!tryLocales.includes("en")) tryLocales.push("en");
+
+  // first try bundled copydecks (ie. available in browser bundle)
+  for (const lang of tryLocales) {
+    if (bundledCopydecks[lang]) {
+      const deck = bundledCopydecks[lang];
+      loadCopydeck(deck);
+      return deck;
+    }
+  }
+
+  // fallback to fetch if base URL is provided (eg. additional copydecks for locales not bundled)
+  if (opts.base) {
+    const baseUrl = new URL(opts.base, window.location.origin);
+    for (const lang of tryLocales) {
+      try {
+        const url = new URL(`${lang}/copydeck.json`, baseUrl).toString();
+        const res = await fetch(url);
+        if (res.ok) {
+          const deck = (await res.json()) as CopyDeck;
+          loadCopydeck(deck);
+          return deck;
+        }
+      } catch {}
+    }
+  }
+
+  throw new Error(`No copydeck found for ${tryLocales.join(", ")}`);
+}
+

src/loaders.ts

@@ -9,9 +9,34 @@ export async function loadCopydeckFor(locale = "en", opts: Options = {}): Promis
   if (baseLang !== locale) tryLocales.push(baseLang);
   if (!tryLocales.includes("en")) tryLocales.push("en");
 
-  const baseUrl = opts.base
-    ? new URL(opts.base, window.location.origin)
-    : new URL("./copydecks/", import.meta.url);
+  let baseUrl: URL;
+  if (opts.base) {
+    baseUrl = new URL(opts.base, window.location.origin);
+  } else {
+    // try to resolve copydecks relative to package location
+    // in bundled environments (webpack/vite), import.meta.url points to the bundle
+    try {
+      const metaUrl = import.meta.url;
+      // construct path dynamically to avoid webpack static analysis
+      const copydecksDir = 'copydecks';
+      const separator = '/';
+      const path = '.' + separator + copydecksDir + separator;
+      
+      // check if this looks like a bundled file
+      if (metaUrl.includes('index.browser.js') || metaUrl.includes('dist/')) {
+        // in a bundled environment, copydecks are in dist/copydecks
+        const bundleDir = metaUrl.substring(0, metaUrl.lastIndexOf('/'));
+        baseUrl = new URL(path, bundleDir);
+      } else {
+        baseUrl = new URL(path, metaUrl);
+      }
+    } catch {
+      throw new Error(
+        'Unable to resolve copydecks path. Please provide the base URL: ' +
+        'loadCopydeckFor(locale, { base: "/path/to/copydecks/" })'
+      );
+    }
+  }
 
   for (const lang of tryLocales) {
     try {
@@ -22,7 +47,7 @@ export async function loadCopydeckFor(locale = "en", opts: Options = {}): Promis
         loadCopydeck(deck);
         return deck;
       }
-    } catch { /* try next */ }
+    } catch {}
   }
   throw new Error(`No copydeck found for ${tryLocales.join(", ")}`);
 }

tsconfig.json

@@ -6,9 +6,12 @@
     "moduleResolution": "Bundler",
     "declaration": true,
     "outDir": "dist",
+    "rootDir": "src",
     "strict": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
   },
-  "include": ["src", "tests"]
+  "include": ["src"],
+  "exclude": ["tests", "node_modules", "dist", "src/**/*.browser.ts"]
 }