@pablozaiden/webapp 0.5.0 → 0.5.2

package/docs/getting-started.md

@@ -107,6 +107,32 @@ renderWebApp(
 `renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
 `WebAppRoot` owns the shell and `.wapp-main-content`; each route component should return a `Page` wrapper so standard content margins, mobile padding and scroll behavior stay consistent.
 
+Use the framework URL helpers for browser API calls, websocket URLs and app-local links instead of deriving paths from `window.location` in each app. They honor `<base>`, explicit `publicBasePath` config, and reverse-proxy subpaths for direct path deep links such as `/workspaces`:
+
+```tsx
+import {
+  appAbsoluteUrl,
+  appFetch,
+  appPath,
+  appRequest,
+  appWebSocketUrl,
+  configureWebAppClient,
+  setWebAppPublicBasePath,
+} from "@pablozaiden/webapp/web";
+
+configureWebAppClient();
+
+const config = await appFetch("/api/config").then((res) => res.json());
+setWebAppPublicBasePath(config.publicBasePath);
+
+const downloadUrl = appPath("/api/items/export");
+const shareUrl = appAbsoluteUrl("/#/items");
+const socket = new WebSocket(appWebSocketUrl("/api/ws"));
+const rawResponse = await appRequest("/api/items");
+```
+
+`appFetch` is the framework JSON API helper and throws `WebAppApiError` for non-OK responses. Use `appRequest` when the app needs a raw `Response`, such as downloads, custom error handling, or compatibility wrappers.
+
 Recommended dev script:
 
 ```json

package/docs/server.md

@@ -127,7 +127,7 @@ For a functional PWA:
 
 | Field | Default | Use when |
 | --- | --- | --- |
-| `web.entry` | `./web/main.tsx` | The app frontend entrypoint lives somewhere else, such as Clanky's `./frontend.tsx` |
+| `web.entry` | `./web/main.tsx` | The app frontend entrypoint lives somewhere else, such as `./frontend.tsx` |
 | `web.shortName` | `appName` | The installed app label should be shorter than the full name |
 | `web.themeColor` | `#111827` | Browser chrome/install metadata should match product branding |
 | `web.backgroundColor` | `#ffffff` | The manifest background should match the app splash/background |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/build/build-binary.ts

@@ -1,5 +1,5 @@
-import { chmodSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, resolve } from "node:path";
 
 export type BunCompileTarget =
   | "bun-linux-x64"
@@ -13,6 +13,9 @@ export interface BuildWebAppBinaryOptions {
   outfile: string;
   target?: BunCompileTarget;
   define?: Record<string, string>;
+  web?: {
+    entry?: string;
+  };
 }
 
 export function getBunCompileTargetFromArgs(argv = Bun.argv): BunCompileTarget | undefined {
@@ -22,21 +25,93 @@ export function getBunCompileTargetFromArgs(argv = Bun.argv): BunCompileTarget |
 
 export async function buildWebAppBinary(options: BuildWebAppBinaryOptions): Promise<void> {
   mkdirSync(dirname(options.outfile), { recursive: true });
-  const result = await Bun.build({
-    entrypoints: [options.entrypoint],
-    target: "bun",
-    minify: true,
-    sourcemap: "external",
-    define: options.define,
-    compile: options.target ? { target: options.target, outfile: options.outfile } : { outfile: options.outfile },
-  });
-  if (!result.success) {
-    for (const log of result.logs) {
-      console.error(log);
+  const packageRoot = findPackageRoot(dirname(resolve(options.entrypoint)));
+  const buildId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const cacheDir = resolve(packageRoot, ".cache", "webapp-build", buildId);
+  try {
+    mkdirSync(cacheDir, { recursive: true });
+    const webEntry = resolve(dirname(resolve(options.entrypoint)), options.web?.entry ?? "./web/main.tsx");
+    const browserEntry = resolve(cacheDir, "webapp-browser-entry.ts");
+    const browserOutDir = resolve(cacheDir, "browser");
+    writeFileSync(browserEntry, `import { createRoot } from "react-dom/client";
+import { configureWebAppRenderer } from "@pablozaiden/webapp/web";
+
+configureWebAppRenderer(createRoot);
+import ${JSON.stringify(webEntry)};
+`);
+    const browserBuild = await Bun.build({
+      entrypoints: [browserEntry],
+      outdir: browserOutDir,
+      target: "browser",
+      minify: true,
+      sourcemap: "external",
+      define: options.define,
+    });
+    if (!browserBuild.success) {
+      for (const log of browserBuild.logs) {
+        console.error(log);
+      }
+      throw new Error("Browser build failed");
+    }
+    const assets = browserBuild.outputs
+      .map((output) => {
+        const ext = extname(output.path).toLowerCase();
+        const publicPath = `/webapp-compiled/${basename(output.path)}`;
+        return {
+          path: publicPath,
+          contentType: contentTypeForOutput(ext),
+          role: ext === ".css" ? "style" : ext === ".js" ? "script" : "asset",
+          body: readFileSync(output.path).toString("base64"),
+        };
+      });
+    const compiledAssetsModule = resolve(cacheDir, "compiled-webapp-assets.ts");
+    writeFileSync(compiledAssetsModule, `globalThis[Symbol.for("webapp.compiledClient")] = ${JSON.stringify({ packageRoot, assets })};
+`);
+    const compiledEntrypoint = resolve(cacheDir, "entrypoint.ts");
+    writeFileSync(compiledEntrypoint, `import "./compiled-webapp-assets";
+import ${JSON.stringify(resolve(options.entrypoint))};
+`);
+    const result = await Bun.build({
+      entrypoints: [compiledEntrypoint],
+      target: "bun",
+      minify: true,
+      sourcemap: "external",
+      define: options.define,
+      compile: options.target ? { target: options.target, outfile: options.outfile } : { outfile: options.outfile },
+    });
+    if (!result.success) {
+      for (const log of result.logs) {
+        console.error(log);
+      }
+      throw new Error("Binary build failed");
     }
-    throw new Error("Binary build failed");
+    if (process.platform !== "win32" && !options.target?.startsWith("bun-windows")) {
+      chmodSync(options.outfile, 0o755);
+    }
+  } finally {
+    rmSync(cacheDir, { recursive: true, force: true });
   }
-  if (process.platform !== "win32" && !options.target?.startsWith("bun-windows")) {
-    chmodSync(options.outfile, 0o755);
+}
+
+function findPackageRoot(start: string): string {
+  let current = start;
+  while (true) {
+    if (existsSync(resolve(current, "package.json"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return start;
+    current = parent;
   }
 }
+
+function contentTypeForOutput(ext: string): string {
+  if (ext === ".js") return "text/javascript; charset=utf-8";
+  if (ext === ".css") return "text/css; charset=utf-8";
+  if (ext === ".svg") return "image/svg+xml; charset=utf-8";
+  if (ext === ".png") return "image/png";
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".map") return "application/json; charset=utf-8";
+  return "application/octet-stream";
+}

package/src/server/create-web-app-server.ts

@@ -134,7 +134,7 @@ export interface WebAppIconsConfig {
 }
 
 type WebDocument = {
-  bundle: HtmlBundleIndex;
+  bundle?: HtmlBundleIndex;
   entryPublicPath: string;
   cacheDir: string;
   html: string;
@@ -143,6 +143,18 @@ type WebDocument = {
   generatedPublicRoutes: Record<string, PublicRouteDefinition>;
 };
 
+type CompiledClientAsset = {
+  path: string;
+  contentType: string;
+  role: "script" | "style" | "asset";
+  body: string;
+};
+
+type CompiledClient = {
+  packageRoot: string;
+  assets: CompiledClientAsset[];
+};
+
 const DEFAULT_WEB_ENTRY = "./web/main.tsx";
 const DEFAULT_THEME_COLOR = "#111827";
 const DEFAULT_BACKGROUND_COLOR = "#ffffff";
@@ -446,11 +458,32 @@ function iconConfig(value: string | URL | WebAppIconConfig | undefined): WebAppI
   return typeof value === "object" && !(value instanceof URL) && "src" in value ? value : { src: value };
 }
 
-function generatedHtml(config: RuntimeConfig, web: WebAppDocumentConfig, relativeEntry: string, relativePrelude: string, themeColor: string, faviconPath: string, appleTouchPath: string): string {
+function compiledClient(): CompiledClient | undefined {
+  const value = (globalThis as { [key: symbol]: unknown })[Symbol.for("webapp.compiledClient")];
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Partial<CompiledClient>;
+  return typeof candidate.packageRoot === "string" && Array.isArray(candidate.assets) ? candidate as CompiledClient : undefined;
+}
+
+function generatedHtml(
+  config: RuntimeConfig,
+  web: WebAppDocumentConfig,
+  relativeEntry: string | undefined,
+  relativePrelude: string | undefined,
+  themeColor: string,
+  faviconPath: string,
+  appleTouchPath: string,
+  compiledAssets?: CompiledClientAsset[],
+): string {
   const title = escapeHtml(web.title ?? config.appName);
   const shortName = escapeAttribute(web.shortName ?? config.appName);
   const htmlFaviconPath = faviconPath.replace(/^\//, "./");
   const htmlAppleTouchPath = appleTouchPath.replace(/^\//, "./");
+  const styleTags = compiledAssets?.filter((asset) => asset.role === "style").map((asset) => `    <link rel="stylesheet" href="${escapeAttribute(asset.path)}" />`).join("\n") ?? "";
+  const scriptTags = compiledAssets
+    ? compiledAssets.filter((asset) => asset.role === "script").map((asset) => `    <script type="module" src="${escapeAttribute(asset.path)}"></script>`).join("\n")
+    : `    <script type="module" src="${escapeAttribute(relativePrelude ?? "")}"></script>
+    <script type="module" src="${escapeAttribute(relativeEntry ?? "")}"></script>`;
   const manifestTags = pwaEnabled(web)
     ? `    <link rel="icon" href="${escapeAttribute(htmlFaviconPath)}" />
     <link rel="apple-touch-icon" href="${escapeAttribute(htmlAppleTouchPath)}" />
@@ -473,11 +506,11 @@ function generatedHtml(config: RuntimeConfig, web: WebAppDocumentConfig, relativ
     <meta name="theme-color" content="${escapeAttribute(themeColor)}" />
 ${manifestTags}    <title>${title}</title>
     <script>${themeBootScript(themeColor)}</script>
+${styleTags}
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="${escapeAttribute(relativePrelude)}"></script>
-    <script type="module" src="${escapeAttribute(relativeEntry)}"></script>
+${scriptTags}
   </body>
 </html>
 `;
@@ -485,11 +518,12 @@ ${manifestTags}    <title>${title}</title>
 
 async function createWebDocument(config: RuntimeConfig, webInput: WebAppDocumentConfig | undefined): Promise<WebDocument> {
   const web = webInput ?? {};
-  const entryFile = resolveWebEntry(web.entry);
+  const compiled = compiledClient();
+  const entryFile = compiled ? undefined : resolveWebEntry(web.entry);
   const themeColor = web.themeColor ?? DEFAULT_THEME_COLOR;
   const backgroundColor = web.backgroundColor ?? DEFAULT_BACKGROUND_COLOR;
-  const packageRoot = findPackageRoot(dirname(resolve(Bun.main || process.argv[1] || entryFile)));
-  const publicEntry = webEntryPublicPath(entryFile, packageRoot);
+  const packageRoot = compiled?.packageRoot ?? findPackageRoot(dirname(resolve(Bun.main || process.argv[1] || (entryFile ?? "."))));
+  const publicEntry = entryFile ? webEntryPublicPath(entryFile, packageRoot) : "";
   const cacheDir = createDocumentCacheDir(config.envPrefix);
   const htmlPath = resolve(cacheDir, `${config.envPrefix.toLowerCase()}-index.html`);
   const icon = generatedIcon(config.appName, themeColor, backgroundColor);
@@ -521,8 +555,8 @@ import { configureWebAppRenderer } from ${JSON.stringify(frameworkWebPath)};
 
 configureWebAppRenderer(createRoot);
 `);
-  const relativeEntry = toWebPath(relative(cacheDir, entryFile));
-  const relativePrelude = toWebPath(relative(cacheDir, preludePath));
+  const relativeEntry = entryFile ? toWebPath(relative(cacheDir, entryFile)) : undefined;
+  const relativePrelude = entryFile ? toWebPath(relative(cacheDir, preludePath)) : undefined;
   const faviconPath = favicon ? `/webapp-favicon${pathExtension(resolveWebAsset(favicon.src, packageRoot)) || ".png"}` : "/webapp-icon.svg";
   const appleTouchPath = appleTouch ? `/webapp-apple-touch-icon${pathExtension(resolveWebAsset(appleTouch.src, packageRoot)) || ".png"}` : faviconPath;
   if (favicon) {
@@ -538,18 +572,28 @@ configureWebAppRenderer(createRoot);
       await copyWebAsset(manifestIconFile, resolve(cacheDir, `webapp-icon-${index + 1}${ext}`));
     }
   }
-  writeFileSync(htmlPath, generatedHtml(config, web, relativeEntry, relativePrelude, themeColor, faviconPath, appleTouchPath));
-  const bundle = (await import(`${pathToFileURL(htmlPath).href}?v=${Date.now()}-${Math.random()}`)).default;
-  if (!isHtmlBundleIndex(bundle)) {
+  const compiledAssets = compiled?.assets;
+  writeFileSync(htmlPath, generatedHtml(config, web, relativeEntry, relativePrelude, themeColor, faviconPath, appleTouchPath, compiledAssets));
+  const bundle = compiledAssets ? undefined : (await import(`${pathToFileURL(htmlPath).href}?v=${Date.now()}-${Math.random()}`)).default;
+  if (!compiledAssets && !isHtmlBundleIndex(bundle)) {
     throw new Error("Generated web document did not produce a Bun HTMLBundle");
   }
-  const html = await Bun.file(bundle.index).text();
+  const html = bundle ? await Bun.file(bundle.index).text() : await Bun.file(htmlPath).text();
   const generatedPublicRoutes: Record<string, PublicRouteDefinition> = {
     "/webapp-icon.svg": {
       headers: { "content-type": "image/svg+xml; charset=utf-8" },
       GET: icon,
     },
   };
+  if (compiledAssets) {
+    for (const asset of compiledAssets) {
+      const body = Buffer.from(asset.body, "base64");
+      generatedPublicRoutes[asset.path] = {
+        headers: { "content-type": asset.contentType },
+        GET: () => body,
+      };
+    }
+  }
   if (favicon) {
     const faviconFile = resolveWebAsset(favicon.src, packageRoot);
     generatedPublicRoutes[faviconPath] = {
@@ -718,10 +762,12 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   const configuredFavicon = iconConfig(input.web?.icons?.favicon);
   const configuredAppleTouch = iconConfig(input.web?.icons?.appleTouch) ?? configuredFavicon;
   const configuredManifestIcons = input.web?.icons?.manifest ?? [];
+  const compiled = compiledClient();
   const webEntryFile = resolveWebEntry(input.web?.entry);
   const webPackageRoot = findPackageRoot(dirname(resolve(Bun.main || process.argv[1] || webEntryFile)));
   const generatedRoutePaths = new Set([
     webEntryPublicPath(webEntryFile, webPackageRoot),
+    ...(compiled?.assets.map((asset) => asset.path) ?? []),
     "/webapp-icon.svg",
     ...(configuredFavicon ? [`/webapp-favicon${pathExtension(resolveWebAsset(configuredFavicon.src, webPackageRoot)) || ".png"}`] : []),
     ...(configuredAppleTouch ? [`/webapp-apple-touch-icon${pathExtension(resolveWebAsset(configuredAppleTouch.src, webPackageRoot)) || ".png"}`] : []),
@@ -737,7 +783,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
           throw new Error(`publicRoutes cannot override framework-owned web route: ${path}`);
         }
       }
-      if (hasOwnPublicRoute(publicRoutes, document.entryPublicPath)) {
+      if (document.entryPublicPath && hasOwnPublicRoute(publicRoutes, document.entryPublicPath)) {
         throw new Error(`publicRoutes cannot override framework-owned web route: ${document.entryPublicPath}`);
       }
       return document;
@@ -1302,22 +1348,26 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       DELETE: dynamicHandler,
       OPTIONS: dynamicHandler,
     };
+    // Bun only transforms HTMLBundle modules/HMR when the bundle is mounted directly.
+    // Wrapping it in a handler or Response, or adding route-level headers, serves
+    // untransformed module paths and breaks generated document routes.
+    const spaDocumentRoute = webDocument.bundle ? {
+      ...spaFallbackRoute,
+      GET: webDocument.bundle as never,
+      HEAD: webDocument.bundle as never,
+    } : spaFallbackRoute;
+    const entryRoute = webDocument.bundle ? { [webDocument.entryPublicPath]: webDocument.bundle as never } : {};
     const server = Bun.serve<WebAppWebSocketData>({
       hostname: config.host,
       port: config.port,
       routes: {
         ...publicRouteHandlers,
-        [webDocument.entryPublicPath]: webDocument.bundle as never,
+        ...entryRoute,
         "/api/*": dynamicHandler,
         "/.well-known/*": dynamicHandler,
-        "/device": dynamicHandler,
-        "/setup": dynamicHandler,
-        "/*": {
-          ...spaFallbackRoute,
-          // Bun only transforms HTMLBundle modules/HMR when the bundle is mounted directly.
-          GET: webDocument.bundle as never,
-          HEAD: webDocument.bundle as never,
-        },
+        "/device": deviceAuthEnabled ? spaDocumentRoute : dynamicHandler,
+        "/setup": spaDocumentRoute,
+        "/*": spaDocumentRoute,
       },
       websocket: {
         open(socket) {

package/src/web/api-client.ts

@@ -15,6 +15,10 @@ export class WebAppApiError extends Error {
 export type AuthRequiredListener = () => void;
 
 const authRequiredListeners = new Set<AuthRequiredListener>();
+let configuredPublicBasePath: string | undefined;
+let configuredApiBaseUrl: string | undefined;
+let configuredWebSocketBaseUrl: string | undefined;
+const ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
 
 export function onAuthRequired(listener: AuthRequiredListener): () => void {
   authRequiredListeners.add(listener);
@@ -27,20 +31,74 @@ function emitAuthRequired(): void {
   }
 }
 
+export function configureWebAppClient(options: {
+  publicBasePath?: string | null;
+  apiBaseUrl?: string | null;
+  wsBaseUrl?: string | null;
+} = {}): void {
+  setWebAppPublicBasePath(options.publicBasePath);
+  configuredApiBaseUrl = normalizeOptionalBaseUrl(options.apiBaseUrl);
+  configuredWebSocketBaseUrl = normalizeOptionalBaseUrl(options.wsBaseUrl);
+}
+
+export function setWebAppPublicBasePath(basePath?: string | null): void {
+  if (basePath == null) {
+    configuredPublicBasePath = undefined;
+    return;
+  }
+
+  const normalizedBasePath = normalizePublicBasePath(basePath);
+  configuredPublicBasePath = normalizedBasePath || undefined;
+}
+
+export function getWebAppPublicBasePath(): string {
+  return configuredPublicBasePath ?? "";
+}
+
 export function appPath(path: string): string {
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) return path;
-  const base = document.querySelector("base")?.getAttribute("href") ?? "/";
-  return new URL(path.replace(/^\/+/, ""), new URL(base, window.location.href)).toString();
+  if (isAbsolutePath(path)) return path;
+  if (configuredApiBaseUrl) {
+    return buildAbsoluteUrl(configuredApiBaseUrl, path);
+  }
+
+  const normalizedPath = path.replace(/^\/+/, "");
+  const configuredBasePath = getWebAppPublicBasePath();
+  if (configuredBasePath) {
+    return new URL(normalizedPath, getConfiguredBaseUrl(configuredBasePath)).toString();
+  }
+
+  return new URL(normalizedPath, getDocumentBaseUrl()).toString();
+}
+
+export function appAbsoluteUrl(path: string): string {
+  if (isAbsolutePath(path)) return path;
+
+  const normalizedPath = path.replace(/^\/+/, "");
+  const configuredBasePath = getWebAppPublicBasePath();
+  if (configuredBasePath) {
+    return new URL(normalizedPath, getConfiguredBaseUrl(configuredBasePath)).toString();
+  }
+
+  return new URL(normalizedPath, getDocumentBaseUrl()).toString();
 }
 
 export function appWebSocketUrl(path = "/api/ws"): string {
-  const url = new URL(appPath(path));
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  const configuredWsBaseUrl = configuredWebSocketBaseUrl ?? configuredApiBaseUrl;
+  const url = new URL(configuredWsBaseUrl ? buildAbsoluteUrl(configuredWsBaseUrl, path) : appAbsoluteUrl(path));
+  if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  } else if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  }
   return url.toString();
 }
 
+export async function appRequest(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  return await fetch(typeof input === "string" ? appPath(input) : input, init);
+}
+
 export async function appFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
-  const response = await fetch(typeof input === "string" ? appPath(input) : input, {
+  const response = await appRequest(input, {
     ...init,
     credentials: init?.credentials ?? "same-origin",
     headers: {
@@ -62,3 +120,42 @@ export async function appFetch(input: RequestInfo | URL, init?: RequestInit): Pr
   }
   return response;
 }
+
+function normalizeOptionalBaseUrl(rawValue?: string | null): string | undefined {
+  const trimmedValue = rawValue?.trim();
+  if (!trimmedValue) {
+    return undefined;
+  }
+
+  return trimmedValue.replace(/\/+$/, "");
+}
+
+function normalizePublicBasePath(rawBasePath?: string | null): string {
+  const trimmedBasePath = rawBasePath?.trim();
+  if (!trimmedBasePath || trimmedBasePath === "/") {
+    return "";
+  }
+
+  const withLeadingSlash = trimmedBasePath.startsWith("/") ? trimmedBasePath : `/${trimmedBasePath}`;
+  const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, "");
+
+  return withoutTrailingSlash === "/" ? "" : withoutTrailingSlash;
+}
+
+function buildAbsoluteUrl(baseUrl: string, path: string): string {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return new URL(normalizedPath, `${baseUrl}/`).toString();
+}
+
+function getDocumentBaseUrl(): URL {
+  const baseHref = document.querySelector("base")?.getAttribute("href");
+  return baseHref ? new URL(baseHref, window.location.href) : new URL(".", window.location.href);
+}
+
+function getConfiguredBaseUrl(basePath: string): URL {
+  return new URL(`${basePath}/`, new URL(window.location.href).origin);
+}
+
+function isAbsolutePath(path: string): boolean {
+  return ABSOLUTE_URL_PATTERN.test(path) || path.startsWith("//");
+}