@pablozaiden/webapp 0.5.3 → 0.5.5

package/docs/deployment.md

@@ -17,6 +17,26 @@ await buildWebAppBinary({
 });
 ```
 
+The binary builder compiles the browser bundle with the framework defaults needed for `webapp` apps, including Tailwind CSS v4 processing. If an app needs extra browser build behavior, add Bun plugins or browser-only defines under `web.build`:
+
+```ts
+await buildWebAppBinary({
+  entrypoint: "src/index.ts",
+  outfile: "./dist/my-app",
+  web: {
+    entry: "./frontend.tsx",
+    build: {
+      plugins: [myBrowserPlugin],
+      define: {
+        "process.env.MY_BROWSER_FLAG": JSON.stringify("enabled"),
+      },
+    },
+  },
+});
+```
+
+App-provided plugins run before the framework defaults. Use `web.build.disableDefaultPlugins` only for specialized builds that intentionally replace the framework browser pipeline.
+
 Run the binary with the same CLI contract:
 
 ```bash

package/docs/github-actions.md

@@ -415,6 +415,8 @@ await buildWebAppBinary({
 });
 ```
 
+`buildWebAppBinary` includes the framework browser build defaults, including Tailwind CSS v4 processing. Apps that need additional browser-only transforms can pass Bun plugins or defines through `web.build.plugins` and `web.build.define`; app plugins run before the framework defaults.
+
 ## Adaptation checklist
 
 1. Replace `my-app` everywhere with the binary name.

package/docs/server.md

@@ -129,7 +129,7 @@ For a functional PWA:
 | --- | --- | --- |
 | `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.themeColor` | Not emitted unless set | Browser chrome/install metadata should match product branding; the generated default icon still uses `#111827` when unset |
 | `web.backgroundColor` | `#ffffff` | The manifest background should match the app splash/background |
 | `web.icons.favicon` | Generated initials SVG | Browser tabs should use product artwork instead of initials |
 | `web.icons.appleTouch` | `favicon` or generated initials SVG | iOS home-screen/Dock should use product artwork |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
   "dependencies": {
     "@simplewebauthn/browser": "13.3.0",
     "@simplewebauthn/server": "13.3.1",
+    "bun-plugin-tailwind": "0.1.2",
     "jose": "6.2.3",
     "tailwindcss": "4.3.1",
     "zod": "4.4.3"

package/src/build/build-binary.ts

@@ -1,3 +1,5 @@
+import type { BunPlugin } from "bun";
+import tailwindPlugin from "bun-plugin-tailwind";
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, resolve } from "node:path";
 
@@ -15,6 +17,11 @@ export interface BuildWebAppBinaryOptions {
   define?: Record<string, string>;
   web?: {
     entry?: string;
+    build?: {
+      plugins?: BunPlugin[];
+      define?: Record<string, string>;
+      disableDefaultPlugins?: boolean;
+    };
   };
 }
 
@@ -41,6 +48,10 @@ configureWebAppRenderer(createRoot);
 `);
     writeFileSync(clientEntry, `import ${JSON.stringify(webEntry)};
 `);
+    const browserPlugins = [
+      ...(options.web?.build?.plugins ?? []),
+      ...(options.web?.build?.disableDefaultPlugins ? [] : [tailwindPlugin]),
+    ];
     const browserBuild = await Bun.build({
       entrypoints: [rendererEntry, clientEntry],
       outdir: browserOutDir,
@@ -50,7 +61,8 @@ configureWebAppRenderer(createRoot);
       publicPath: "/webapp-compiled/",
       minify: true,
       sourcemap: "external",
-      define: options.define,
+      define: { ...options.define, ...options.web?.build?.define },
+      plugins: browserPlugins,
     });
     if (!browserBuild.success) {
       for (const log of browserBuild.logs) {

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

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -181,7 +181,7 @@ function safeCachePathSegment(value: string): string {
 function createDocumentCacheDir(envPrefix: string): string {
   const root = join(tmpdir(), "webapp", safeCachePathSegment(envPrefix));
   mkdirSync(root, { recursive: true });
-  const cacheDir = mkdtempSync(join(root, WEBAPP_DOCUMENT_CACHE_PREFIX));
+  const cacheDir = realpathSync(mkdtempSync(join(root, WEBAPP_DOCUMENT_CACHE_PREFIX)));
   documentCacheDirs.add(cacheDir);
   if (!documentCacheCleanupRegistered) {
     documentCacheCleanupRegistered = true;
@@ -413,13 +413,15 @@ function contentTypeForIcon(path: string, explicit?: string): string {
   return "application/octet-stream";
 }
 
-function themeBootScript(themeColor: string): string {
-  const darkThemeColor = JSON.stringify(themeColor);
-  const lightThemeColor = JSON.stringify(DEFAULT_BACKGROUND_COLOR);
+function themeBootScript(themeColor: string | undefined): string {
+  const themeColorUpdate = themeColor
+    ? `
+  const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+  if (metaThemeColor instanceof HTMLMetaElement) metaThemeColor.content = resolved === "dark" ? ${JSON.stringify(themeColor)} : ${JSON.stringify(DEFAULT_BACKGROUND_COLOR)};`
+    : "";
   return `(() => {
   const key = "webapp.theme";
   const root = document.documentElement;
-  const metaThemeColor = document.querySelector('meta[name="theme-color"]');
   const stored = window.localStorage.getItem(key);
   const preference = stored === "light" || stored === "dark" || stored === "system" ? stored : "system";
   const systemDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
@@ -428,7 +430,7 @@ function themeBootScript(themeColor: string): string {
   root.style.colorScheme = resolved;
   root.dataset.theme = preference;
   root.dataset.resolvedTheme = resolved;
-  if (metaThemeColor instanceof HTMLMetaElement) metaThemeColor.content = resolved === "dark" ? ${darkThemeColor} : ${lightThemeColor};
+${themeColorUpdate}
 })();`;
 }
 
@@ -440,7 +442,7 @@ function pwaConfig(web: WebAppDocumentConfig): WebAppPwaConfig {
   return typeof web.pwa === "object" ? web.pwa : {};
 }
 
-function generatedManifest(config: RuntimeConfig, web: WebAppDocumentConfig, themeColor: string, backgroundColor: string, icons: WebAppIconConfig[]): string {
+function generatedManifest(config: RuntimeConfig, web: WebAppDocumentConfig, backgroundColor: string, icons: WebAppIconConfig[]): string {
   const pwa = pwaConfig(web);
   return JSON.stringify({
     name: config.appName,
@@ -449,7 +451,7 @@ function generatedManifest(config: RuntimeConfig, web: WebAppDocumentConfig, the
     scope: pwa.scope ?? "./",
     display: pwa.display ?? "standalone",
     background_color: backgroundColor,
-    theme_color: themeColor,
+    ...(web.themeColor ? { theme_color: web.themeColor } : {}),
     icons,
   }, null, 2);
 }
@@ -471,7 +473,7 @@ function generatedHtml(
   web: WebAppDocumentConfig,
   relativeEntry: string | undefined,
   relativePrelude: string | undefined,
-  themeColor: string,
+  themeColor: string | undefined,
   faviconPath: string,
   appleTouchPath: string,
   compiledAssets?: CompiledClientAsset[],
@@ -480,6 +482,7 @@ function generatedHtml(
   const shortName = escapeAttribute(web.shortName ?? config.appName);
   const htmlFaviconPath = faviconPath.replace(/^\//, "./");
   const htmlAppleTouchPath = appleTouchPath.replace(/^\//, "./");
+  const themeMetaTag = themeColor ? `    <meta name="theme-color" content="${escapeAttribute(themeColor)}" />\n` : "";
   const styleTags = compiledAssets?.filter((asset) => asset.role === "style").map((asset) => `    <link rel="stylesheet" href="${escapeAttribute(asset.path)}" />`).join("\n") ?? "";
   const scriptTags = compiledAssets
     ? compiledAssets
@@ -508,7 +511,7 @@ function generatedHtml(
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-    <meta name="theme-color" content="${escapeAttribute(themeColor)}" />
+${themeMetaTag}\
 ${manifestTags}    <title>${title}</title>
     <script>${themeBootScript(themeColor)}</script>
 ${styleTags}
@@ -525,13 +528,13 @@ async function createWebDocument(config: RuntimeConfig, webInput: WebAppDocument
   const web = webInput ?? {};
   const compiled = compiledClient();
   const entryFile = compiled ? undefined : resolveWebEntry(web.entry);
-  const themeColor = web.themeColor ?? DEFAULT_THEME_COLOR;
+  const iconThemeColor = web.themeColor ?? DEFAULT_THEME_COLOR;
   const backgroundColor = web.backgroundColor ?? DEFAULT_BACKGROUND_COLOR;
   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);
+  const icon = generatedIcon(config.appName, iconThemeColor, backgroundColor);
   const favicon = iconConfig(web.icons?.favicon);
   const appleTouch = iconConfig(web.icons?.appleTouch) ?? favicon;
   const manifestIconConfigs = web.icons?.manifest?.length ? web.icons.manifest : undefined;
@@ -547,7 +550,7 @@ async function createWebDocument(config: RuntimeConfig, webInput: WebAppDocument
         };
       })
     : [{ src: "./webapp-icon.svg", sizes: "any", type: "image/svg+xml", purpose: "any maskable" }];
-  const manifest = pwaEnabled(web) ? generatedManifest(config, web, themeColor, backgroundColor, manifestIcons) : "";
+  const manifest = pwaEnabled(web) ? generatedManifest(config, web, backgroundColor, manifestIcons) : "";
   writeFileSync(resolve(cacheDir, "webapp-icon.svg"), icon);
   if (manifest) {
     writeFileSync(resolve(cacheDir, "site.webmanifest"), manifest);
@@ -578,7 +581,7 @@ configureWebAppRenderer(createRoot);
     }
   }
   const compiledAssets = compiled?.assets;
-  writeFileSync(htmlPath, generatedHtml(config, web, relativeEntry, relativePrelude, themeColor, faviconPath, appleTouchPath, compiledAssets));
+  writeFileSync(htmlPath, generatedHtml(config, web, relativeEntry, relativePrelude, web.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");