@pablozaiden/webapp 0.4.0 → 0.4.1

package/docs/getting-started.md

@@ -48,7 +48,21 @@ const app = createWebAppServer({
 await app.runFromCli();
 ```
 
-The `pwa` option is optional; by default the framework derives install metadata from `appName`, serves `/manifest.webmanifest`, and injects the manifest/icon/mobile head tags into the shell HTML. Configure `icons`, `appleTouchIcon`, `startUrl`, and `scope` when your app ships specific install assets.
+The `pwa` option is optional; by default the framework derives install metadata from `appName` and serves `/manifest.webmanifest`. Configure `icons`, `appleTouchIcon`, `startUrl`, and `scope` when your app serves the manifest dynamically through the framework.
+
+For the recommended Bun `HTMLBundle` shape (`import webIndex from "./index.html"`), keep the install metadata static and relative to `index.html` so Bun can bundle and rewrite those assets:
+
+```html
+<link rel="manifest" href="./site.webmanifest" />
+<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
+<link rel="apple-touch-icon" href="./apple-touch-icon.png" />
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-title" content="MyApp" />
+<meta name="theme-color" content="#111827" />
+```
+
+Place `site.webmanifest`, icons, and apple-touch icons next to `index.html`, and reference manifest icons with relative paths such as `"./web-app-manifest-192x192.png"`. A single SVG favicon is enough for lightweight examples; production apps should include PNG manifest icons and an Apple touch icon like Clanky. For string, `Blob`, or `Response` HTML indexes, the framework injects equivalent tags automatically.
 
 Apps should stay one app and one binary. Use subcommands for different modes:
 

package/docs/server.md

@@ -96,7 +96,7 @@ Built-in endpoints include:
 
 ## PWA metadata
 
-`createWebAppServer` provides shell-level PWA metadata so apps do not need to duplicate manifest and icon tags in every `index.html`. PWA support is enabled by default with `appName`-derived manifest values, `/manifest.webmanifest`, `/` start/scope, `standalone` display, and conventional icon paths (`/web-app-manifest-192x192.png`, `/web-app-manifest-512x512.png`, and `/apple-touch-icon.png`).
+`createWebAppServer` provides shell-level PWA metadata. PWA support is enabled by default with `appName`-derived manifest values, `/manifest.webmanifest`, `/` start/scope, `standalone` display, and conventional icon paths (`/web-app-manifest-192x192.png`, `/web-app-manifest-512x512.png`, and `/apple-touch-icon.png`).
 
 ```ts
 createWebAppServer({
@@ -118,7 +118,9 @@ createWebAppServer({
 });
 ```
 
-The framework serves the manifest with `application/manifest+json; charset=utf-8` and injects the installability tags into HTML shell responses:
+The framework serves the manifest with `application/manifest+json; charset=utf-8`.
+
+For string, `Blob`, or `Response` HTML indexes, the framework also injects the installability tags into HTML shell responses:
 
 ```html
 <link rel="manifest" href="/manifest.webmanifest" />
@@ -130,6 +132,37 @@ The framework serves the manifest with `application/manifest+json; charset=utf-8
 <meta name="theme-color" content="#111827" />
 ```
 
+For Bun `HTMLBundle` indexes imported from `index.html`, Bun must serve the HTML and generated assets directly so module rewriting and transpilation keep working. In that mode the framework still serves `/manifest.webmanifest`, but it does not mutate the HTML response. Follow the Clanky-style static asset pattern instead: place `site.webmanifest`, favicons, and apple-touch icons next to `index.html`, then reference them with relative paths so Bun can bundle and rewrite them:
+
+```html
+<link rel="manifest" href="./site.webmanifest" />
+<link rel="icon" href="./favicon.ico" sizes="any" />
+<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
+<link rel="apple-touch-icon" href="./apple-touch-icon.png" />
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-title" content="MyApp" />
+<meta name="theme-color" content="#111827" />
+```
+
+Use relative icon paths inside `site.webmanifest` as well:
+
+```json
+{
+  "name": "My App",
+  "short_name": "MyApp",
+  "start_url": "./",
+  "scope": "./",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#111827",
+  "icons": [
+    { "src": "./web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
+    { "src": "./web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
+  ]
+}
+```
+
 Icon files still need to exist in the app bundle or public routes; the framework advertises and serves metadata, but it does not generate image assets. Set `pwa: { enabled: false }` to opt out. Apps that already serve `/manifest.webmanifest` through `publicRoutes` can keep that override; explicit public routes take precedence over the generated manifest.
 
 ## Public/static routes

package/package.json

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

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

@@ -1105,6 +1105,8 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     const dynamicHandler = (req: Request, server: Server<WebAppWebSocketData>) => handleRequest(req, server);
     const publicRouteHandlers = Object.fromEntries(Object.keys(publicRoutes).map((path) => [path, dynamicHandler]));
     const pwaRouteHandlers = pwa && !hasOwnPublicRoute(publicRoutes, pwa.manifestPath) ? { [pwa.manifestPath]: dynamicHandler } : {};
+    const indexCanRespond = canRespondWithIndex(input.index);
+    const indexIsHtmlBundle = isHtmlBundleIndex(input.index);
     const server = Bun.serve<WebAppWebSocketData>({
       hostname: config.host,
       port: config.port,
@@ -1113,9 +1115,9 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         ...pwaRouteHandlers,
         "/api/*": dynamicHandler,
         "/.well-known/*": dynamicHandler,
-        "/device": deviceAuthEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
-        "/setup": passkeysEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
-        "/*": canRespondWithIndex(input.index) ? dynamicHandler : input.index as never,
+        "/device": deviceAuthEnabled && (!indexCanRespond || indexIsHtmlBundle) ? input.index as never : dynamicHandler,
+        "/setup": passkeysEnabled && (!indexCanRespond || indexIsHtmlBundle) ? input.index as never : dynamicHandler,
+        "/*": indexCanRespond && !indexIsHtmlBundle ? dynamicHandler : input.index as never,
       },
       websocket: {
         open(socket) {