@pablozaiden/webapp 0.5.2 → 0.5.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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;
+    };
   };
 }
 
@@ -31,21 +38,31 @@ export async function buildWebAppBinary(options: BuildWebAppBinaryOptions): Prom
   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 rendererEntry = resolve(cacheDir, "webapp-renderer-prelude.ts");
+    const clientEntry = resolve(cacheDir, "webapp-client-entry.ts");
     const browserOutDir = resolve(cacheDir, "browser");
-    writeFileSync(browserEntry, `import { createRoot } from "react-dom/client";
+    writeFileSync(rendererEntry, `import { createRoot } from "react-dom/client";
 import { configureWebAppRenderer } from "@pablozaiden/webapp/web";
 
 configureWebAppRenderer(createRoot);
-import ${JSON.stringify(webEntry)};
 `);
+    writeFileSync(clientEntry, `import ${JSON.stringify(webEntry)};
+`);
+    const browserPlugins = [
+      ...(options.web?.build?.plugins ?? []),
+      ...(options.web?.build?.disableDefaultPlugins ? [] : [tailwindPlugin]),
+    ];
     const browserBuild = await Bun.build({
-      entrypoints: [browserEntry],
+      entrypoints: [rendererEntry, clientEntry],
       outdir: browserOutDir,
       target: "browser",
+      format: "esm",
+      splitting: true,
+      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) {
@@ -54,13 +71,17 @@ import ${JSON.stringify(webEntry)};
       throw new Error("Browser build failed");
     }
     const assets = browserBuild.outputs
+      .filter((output) => extname(output.path).toLowerCase() !== ".map")
       .map((output) => {
         const ext = extname(output.path).toLowerCase();
+        const fileName = basename(output.path);
         const publicPath = `/webapp-compiled/${basename(output.path)}`;
+        const scriptKind = ext === ".js" ? compiledScriptKind(fileName) : undefined;
         return {
           path: publicPath,
           contentType: contentTypeForOutput(ext),
-          role: ext === ".css" ? "style" : ext === ".js" ? "script" : "asset",
+          role: ext === ".css" ? "style" : scriptKind ? "script" : "asset",
+          ...(scriptKind ? { scriptOrder: scriptKind === "renderer" ? 0 : 1 } : {}),
           body: readFileSync(output.path).toString("base64"),
         };
       });
@@ -115,3 +136,9 @@ function contentTypeForOutput(ext: string): string {
   if (ext === ".map") return "application/json; charset=utf-8";
   return "application/octet-stream";
 }
+
+function compiledScriptKind(fileName: string): "renderer" | "client" | undefined {
+  if (/^webapp-renderer-prelude(?:[-.][\w-]+)?\.(?:mjs|js)$/.test(fileName)) return "renderer";
+  if (/^webapp-client-entry(?:[-.][\w-]+)?\.(?:mjs|js)$/.test(fileName)) return "client";
+  return undefined;
+}

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";
@@ -147,6 +147,7 @@ type CompiledClientAsset = {
   path: string;
   contentType: string;
   role: "script" | "style" | "asset";
+  scriptOrder?: number;
   body: string;
 };
 
@@ -180,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;
@@ -481,7 +482,11 @@ function generatedHtml(
   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")
+    ? compiledAssets
+        .filter((asset) => asset.role === "script")
+        .sort((left, right) => (left.scriptOrder ?? 0) - (right.scriptOrder ?? 0))
+        .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)