@pablozaiden/webapp 0.5.0 → 0.5.1

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.1",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

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

@@ -1302,6 +1302,14 @@ 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 = {
+      ...spaFallbackRoute,
+      GET: webDocument.bundle as never,
+      HEAD: webDocument.bundle as never,
+    };
     const server = Bun.serve<WebAppWebSocketData>({
       hostname: config.host,
       port: config.port,
@@ -1310,14 +1318,9 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         [webDocument.entryPublicPath]: webDocument.bundle as never,
         "/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("//");
+}