alabjs 0.1.1 → 0.2.1

package/src/components/Dynamic.tsx

@@ -0,0 +1,124 @@
+/**
+ * Alab PPR — Partial Prerendering support.
+ *
+ * Pages that export `export const ppr = true` get their static HTML shell
+ * pre-rendered at build time and stored in `.alabjs/ppr-cache/`. At runtime,
+ * the shell is served instantly (CDN-cacheable) while `<Dynamic>` sections
+ * fill in per-request via React's Suspense streaming or client-side hydration.
+ *
+ * ## How it works
+ *
+ * During the **build-time static render** (pre-render pass):
+ *   • `PPRShellProvider` sets the PPR context to `true`.
+ *   • `<Dynamic>` sees the context and renders only its `fallback` inside a
+ *     `data-ppr-hole` marker — children are omitted entirely.
+ *   • The resulting HTML is the "static shell": complete page minus dynamic parts.
+ *
+ * At **runtime**:
+ *   • `PPRShellProvider` is never rendered → context defaults to `false`.
+ *   • `<Dynamic>` behaves as a plain `<Suspense>` boundary, streaming children
+ *     as their async work resolves.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // app/posts/[id]/page.tsx
+ * import { Dynamic } from "alabjs/components";
+ *
+ * export const ppr = true;
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   return (
+ *     <article>
+ *       <h1>Post {params.id}</h1>
+ *       <Dynamic id="sidebar" fallback={<SidebarSkeleton />}>
+ *         <PersonalisedSidebar userId={userId} />
+ *       </Dynamic>
+ *     </article>
+ *   );
+ * }
+ * ```
+ */
+
+import { Suspense, createContext, useContext, type ReactNode } from "react";
+
+// ─── PPR shell context ─────────────────────────────────────────────────────────
+
+/**
+ * When `true`, `<Dynamic>` renders only its `fallback` placeholder.
+ * Set exclusively by `PPRShellProvider` during build-time pre-renders.
+ */
+const PPRShellCtx = createContext(false);
+
+/**
+ * @internal
+ * Wrap the root element with this during build-time PPR pre-rendering so that
+ * every `<Dynamic>` in the tree emits a stable `data-ppr-hole` placeholder
+ * instead of its children.
+ *
+ * Do **not** use this at runtime — it is an implementation detail of
+ * `preRenderPPRShell` in `src/ssr/ppr.ts`.
+ */
+export function PPRShellProvider({ children }: { children: ReactNode }) {
+  return <PPRShellCtx.Provider value={true}>{children}</PPRShellCtx.Provider>;
+}
+
+// ─── Dynamic component ────────────────────────────────────────────────────────
+
+export interface DynamicProps {
+  /**
+   * Unique identifier for this dynamic section within the page.
+   *
+   * Used to correlate the placeholder emitted in the static shell with the
+   * live content streamed at runtime. **Must be stable across renders** —
+   * treat it like a React key: short, descriptive, no dynamic values.
+   *
+   * @example "sidebar", "user-nav", "related-posts"
+   */
+  id: string;
+  /** Per-request dynamic content. Never rendered in the pre-built static shell. */
+  children: ReactNode;
+  /**
+   * Shown in the pre-built static shell **and** as the React Suspense fallback
+   * while the dynamic content is streaming in.
+   *
+   * Keep this lightweight — it is inlined into every CDN-cached response.
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Marks a subtree as **dynamic** (per-request) within a PPR page.
+ *
+ * - **Build time** (static shell pre-render): renders `fallback` inside a
+ *   `<div data-ppr-hole="{id}">` marker. Children are not rendered.
+ * - **Runtime** (SSR + hydration): acts as a `<Suspense>` boundary. Children
+ *   stream in as their async work resolves; `fallback` is shown meanwhile.
+ *
+ * The `display: contents` style on the wrapper div means it has no visual
+ * footprint — it exists only as a DOM anchor for Alab's PPR machinery.
+ */
+export function Dynamic({ id, children, fallback = null }: DynamicProps) {
+  const isShell = useContext(PPRShellCtx);
+
+  const holeWrapper = (content: ReactNode) => (
+    <div data-ppr-hole={id} style={{ display: "contents" }}>
+      {content}
+    </div>
+  );
+
+  if (isShell) {
+    // Build-time pre-render: emit only the placeholder + fallback.
+    // Children are intentionally omitted — they contain per-request logic.
+    return holeWrapper(fallback);
+  }
+
+  // Runtime: standard Suspense boundary.
+  // The hole wrapper on the fallback preserves the DOM anchor so client-side
+  // hydration can match it to the pre-rendered shell.
+  return (
+    <Suspense fallback={holeWrapper(fallback)}>
+      {children}
+    </Suspense>
+  );
+}

package/src/components/index.ts

@@ -7,3 +7,7 @@ export { Script } from "./Script.js";
 export type { ScriptProps } from "./Script.js";
 export { Font } from "./Font.js";
 export type { FontProps } from "./Font.js";
+export { Dynamic, PPRShellProvider } from "./Dynamic.js";
+export type { DynamicProps } from "./Dynamic.js";
+export { Analytics } from "./Analytics.js";
+export type { AnalyticsProps } from "./Analytics.js";

package/src/index.ts

@@ -6,5 +6,6 @@ export type {
   PageMetadata,
   GenerateMetadata,
   RouteParams,
+  CdnCache,
 } from "./types/index.js";
 export { createApp } from "./server/app.js";

package/src/server/app.ts

@@ -1,7 +1,7 @@
 import { createApp as createH3App, createRouter, defineEventHandler, getQuery, readBody } from "h3";
 import { createServer } from "node:http";
 import { resolve, dirname, join, extname } from "node:path";
-import { existsSync, createReadStream, statSync } from "node:fs";
+import { existsSync, createReadStream, statSync, readFileSync } from "node:fs";
 import { toNodeListener } from "h3";
 import type { RouteManifest } from "../router/manifest.js";
 import { renderToResponse } from "../ssr/render.js";
@@ -12,6 +12,9 @@ import type { MiddlewareModule } from "./middleware.js";
 import { runMiddleware } from "./middleware.js";
 import type { PageMetadata } from "../types/index.js";
 import { checkRevalidateAuth, applyRevalidate } from "./revalidate.js";
+import { applyCdnHeaders, type CdnCache } from "./cdn.js";
+import { getPPRShell, injectBuildIdIntoPPRShell, PPR_CACHE_SUBDIR } from "../ssr/ppr.js";
+import { handleVitalsBeacon, handleAnalyticsDashboard } from "../analytics/handler.js";
 
 /**
  * Find layout file paths (relative to cwd root) for a given route.file, ordered outermost→innermost.
@@ -75,6 +78,17 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
   const router = createRouter();
   const publicDir = resolve(distDir, "../../public");
 
+  // Load the build ID written by `alab build` for skew protection.
+  // If the file is absent (first-run / non-standard setup) skew detection
+  // is silently disabled — existing behaviour is unchanged.
+  let buildId: string | undefined;
+  try {
+    buildId = readFileSync(resolve(distDir, "BUILD_ID"), "utf8").trim() || undefined;
+  } catch { /* no BUILD_ID file — skew protection disabled */ }
+
+  // Absolute path to the PPR shell cache directory.
+  const pprCacheDir = resolve(distDir, "../../", PPR_CACHE_SUBDIR);
+
   // ─── Global middleware ───────────────────────────────────────────────────────
   app.use(
     defineEventHandler((event) => {
@@ -230,6 +244,23 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
     }),
   );
 
+  // Core Web Vitals beacon — receives POST from <Analytics> component
+  router.post(
+    "/_alabjs/vitals",
+    defineEventHandler((event) => {
+      return handleVitalsBeacon(event.node.req, event.node.res);
+    }),
+  );
+
+  // Analytics dashboard — GET aggregated per-route stats
+  router.get(
+    "/_alabjs/analytics",
+    defineEventHandler((event) => {
+      handleAnalyticsDashboard(event.node.req, event.node.res);
+      return null;
+    }),
+  );
+
   // Auto sitemap.xml from route manifest
   router.get(
     "/sitemap.xml",
@@ -319,12 +350,14 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
       defineEventHandler(async (event) => {
         const res = event.node.res;
 
-        // HTML pages must not be cached by intermediaries — they contain
-        // user-specific CSRF tokens and may reflect auth state.
-        res.setHeader("cache-control", "no-store");
-
-        // Set CSRF cookie so the client can send it on mutations.
-        const csrfToken = setCsrfCookie(event);
+        // Skew protection: tell the client which build this server is running.
+        if (buildId) {
+          res.setHeader("x-alab-build-id", buildId);
+          const clientBuildId = event.node.req.headers["x-alab-build-id"];
+          if (clientBuildId && clientBuildId !== buildId) {
+            res.setHeader("x-alab-revalidate", "1");
+          }
+        }
 
         const rawParams = (event.context.params ?? {}) as Record<string, string>;
         const params = rawParams;
@@ -342,6 +375,8 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
           metadata?: PageMetadata;
           generateMetadata?: (params: Record<string, string>) => PageMetadata | Promise<PageMetadata>;
           ssr?: boolean;
+          cdnCache?: CdnCache;
+          ppr?: boolean;
         };
 
         const Page = mod.default;
@@ -351,6 +386,31 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
           return;
         }
 
+        // ── PPR: serve pre-rendered static shell ──────────────────────────────
+        // Pages with `export const ppr = true` get a static HTML shell built
+        // at `alab build` time. Serve it instantly with a long CDN TTL so the
+        // static portion is edge-cached. Dynamic sections (`<Dynamic>`) render
+        // their fallback in the shell and are filled in client-side via React
+        // hydration, or server-side via Suspense streaming on direct hits.
+        if (mod.ppr === true) {
+          let shell = getPPRShell(route.path, pprCacheDir);
+          if (shell !== null) {
+            // Inject the per-build skew-protection tag into the pre-rendered HTML.
+            if (buildId) shell = injectBuildIdIntoPPRShell(shell, buildId);
+
+            res.statusCode = 200;
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            // Long CDN TTL: static shell doesn't change until the next build.
+            res.setHeader("cache-control", "public, s-maxage=3600, stale-while-revalidate=86400");
+            res.setHeader("x-alab-ppr", "shell");
+            if (buildId) res.setHeader("x-alab-build-id", buildId);
+            res.end(shell);
+            return;
+          }
+          // Shell not found — fall through to normal SSR and warn once.
+          console.warn(`[alabjs] ppr: no pre-rendered shell for ${route.path} — run \`alab build\` to generate it. Falling back to SSR.`);
+        }
+
         // Support both static metadata and dynamic generateMetadata (production fix)
         const metadata: PageMetadata =
           typeof mod.generateMetadata === "function"
@@ -369,8 +429,20 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
         const layoutsJson = JSON.stringify(layoutRelPaths);
         const loadingFile = findProdLoadingFile(route.file, distDir) ?? undefined;
 
-        // Inject CSRF token into the HTML head so client JS can read it.
-        const headExtra = `<meta name="csrf-token" content="${csrfToken.replace(/"/g, "&quot;")}" />`;
+        // ── Cache-control + CSRF ──────────────────────────────────────────────
+        // Pages that export `cdnCache` are public, edge-cacheable pages.
+        // They get CDN headers instead of `no-store`, and CSRF tokens are
+        // omitted — a shared cache would deliver the same token to every
+        // visitor, defeating CSRF protection.
+        let headExtra = "";
+        if (mod.cdnCache) {
+          applyCdnHeaders(res, mod.cdnCache);
+        } else {
+          // Private page: must not be cached by intermediaries.
+          res.setHeader("cache-control", "no-store");
+          const csrfToken = setCsrfCookie(event);
+          headExtra = `<meta name="csrf-token" content="${csrfToken.replace(/"/g, "&quot;")}" />`;
+        }
 
         try {
           renderToResponse(res, {
@@ -384,6 +456,7 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
             loadingFile,
             ssr: ssrEnabled,
             headExtra,
+            ...(buildId ? { buildId } : {}),
           });
         } catch (err) {
           // ── error.tsx fallback ────────────────────────────────────────────

package/src/server/cdn.ts

@@ -0,0 +1,187 @@
+/**
+ * CDN cache header utilities for Alab.
+ *
+ * Pages that export `const cdnCache: CdnCache = { ... }` are opt-in public,
+ * edge-cached pages. Alab sets response headers so any CDN or shared proxy
+ * (Cloudflare, Fastly, Varnish, Nginx, AWS CloudFront) can cache them without
+ * Vercel.
+ *
+ * ## Configuration
+ *
+ * Set `ALAB_CDN` in your environment to enable vendor-specific headers:
+ *
+ *   | Value        | Extra headers set                               |
+ *   |--------------|-------------------------------------------------|
+ *   | `cloudflare` | `CDN-Cache-Control`, `Cache-Tag`                |
+ *   | `fastly`     | `Surrogate-Control`, `Surrogate-Key`            |
+ *   | (unset)      | Universal `Cache-Control: public, s-maxage=N` only |
+ *
+ * ## Tag-based purge credentials
+ *
+ *   - Cloudflare: `CF_ZONE_ID` + `CF_API_TOKEN`
+ *   - Fastly:     `FASTLY_SERVICE_ID` + `FASTLY_API_KEY`
+ *
+ * ## Important
+ *
+ * CDN-cached pages are **public pages** — they must not contain user-specific
+ * state. Alab automatically skips CSRF token injection for pages that export
+ * `cdnCache` because a shared cache would hand the same token to every visitor,
+ * which defeats CSRF protection.
+ */
+
+import type { ServerResponse } from "node:http";
+
+// ─── Public type ──────────────────────────────────────────────────────────────
+
+export interface CdnCache {
+  /** Seconds the CDN / shared proxy may cache this response. */
+  maxAge: number;
+  /**
+   * Seconds the CDN may continue serving a stale response while it
+   * revalidates the entry in the background (stale-while-revalidate).
+   * Defaults to `maxAge` when omitted.
+   */
+  swr?: number;
+  /**
+   * Cache tags for targeted invalidation via `POST /_alabjs/revalidate`.
+   *
+   * - Cloudflare: emitted as `Cache-Tag: tag1,tag2`
+   * - Fastly / Varnish: emitted as `Surrogate-Key: tag1 tag2`
+   *
+   * @example
+   * export const cdnCache: CdnCache = {
+   *   maxAge: 60,
+   *   tags: ["posts", "post:42"],
+   * };
+   */
+  tags?: readonly string[];
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────────
+
+type CdnProvider = "cloudflare" | "fastly" | "none";
+
+function detectProvider(): CdnProvider {
+  switch (process.env["ALAB_CDN"]?.toLowerCase()) {
+    case "cloudflare": return "cloudflare";
+    case "fastly":     return "fastly";
+    default:           return "none";
+  }
+}
+
+// ─── Header helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Set CDN-appropriate response headers for a page that opts in to edge caching
+ * via `export const cdnCache = { ... }`.
+ *
+ * Always emits the universal `Cache-Control: public, s-maxage=N,
+ * stale-while-revalidate=M` header. Vendor-specific headers are added when
+ * `ALAB_CDN` is set.
+ */
+export function applyCdnHeaders(res: ServerResponse, cdnCache: CdnCache): void {
+  const { maxAge, swr = maxAge, tags = [] } = cdnCache;
+
+  // Universal — honoured by every shared proxy, CDN, and browser.
+  res.setHeader(
+    "cache-control",
+    `public, s-maxage=${maxAge}, stale-while-revalidate=${swr}`,
+  );
+
+  const provider = detectProvider();
+
+  if (provider === "cloudflare") {
+    // Cloudflare reads CDN-Cache-Control with higher priority than Cache-Control,
+    // allowing different TTLs at the edge vs. the browser.
+    res.setHeader("cdn-cache-control", `max-age=${maxAge}`);
+    if (tags.length > 0) {
+      // Cache-Tag enables Cloudflare tag-based purge via their API.
+      res.setHeader("cache-tag", [...tags].join(","));
+    }
+  } else if (provider === "fastly") {
+    // Surrogate-Control is stripped by Fastly before forwarding to the browser,
+    // so it can hold a much larger TTL than Cache-Control safely.
+    res.setHeader("surrogate-control", `max-age=${maxAge}`);
+    if (tags.length > 0) {
+      // Surrogate-Key is Fastly's mechanism for instant surrogate-key purge.
+      res.setHeader("surrogate-key", [...tags].join(" "));
+    }
+  }
+}
+
+// ─── CDN purge ────────────────────────────────────────────────────────────────
+
+/**
+ * Purge CDN cache entries by tag.
+ *
+ * Called from `/_alabjs/revalidate` **after** the in-process cache has been
+ * cleared. Silently no-ops when `ALAB_CDN` is not configured or the required
+ * credentials are absent — the TTL will expire the CDN entry naturally.
+ */
+export async function purgeCdnByTags(tags: readonly string[]): Promise<void> {
+  if (tags.length === 0) return;
+
+  switch (detectProvider()) {
+    case "cloudflare": await purgeCloudflare(tags); break;
+    case "fastly":     await purgeFastly(tags);     break;
+    // "none": no CDN purge needed — in-process cache already cleared.
+  }
+}
+
+async function purgeCloudflare(tags: readonly string[]): Promise<void> {
+  const zoneId   = process.env["CF_ZONE_ID"];
+  const apiToken = process.env["CF_API_TOKEN"];
+
+  if (!zoneId || !apiToken) {
+    console.warn(
+      "[alabjs] CDN purge: ALAB_CDN=cloudflare but CF_ZONE_ID or CF_API_TOKEN is not set — skipping.",
+    );
+    return;
+  }
+
+  const res = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${apiToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ tags: [...tags] }),
+    },
+  );
+
+  if (!res.ok) {
+    console.error(`[alabjs] Cloudflare cache purge failed (${res.status}): ${await res.text()}`);
+  }
+}
+
+async function purgeFastly(tags: readonly string[]): Promise<void> {
+  const serviceId = process.env["FASTLY_SERVICE_ID"];
+  const apiKey    = process.env["FASTLY_API_KEY"];
+
+  if (!serviceId || !apiKey) {
+    console.warn(
+      "[alabjs] CDN purge: ALAB_CDN=fastly but FASTLY_SERVICE_ID or FASTLY_API_KEY is not set — skipping.",
+    );
+    return;
+  }
+
+  // Fastly instant purge by surrogate key (POST /service/{id}/purge with
+  // Surrogate-Key header containing space-separated tags).
+  const res = await fetch(
+    `https://api.fastly.com/service/${serviceId}/purge`,
+    {
+      method: "POST",
+      headers: {
+        "fastly-key":    apiKey,
+        "surrogate-key": [...tags].join(" "),
+        accept:          "application/json",
+      },
+    },
+  );
+
+  if (!res.ok) {
+    console.error(`[alabjs] Fastly cache purge failed (${res.status}): ${await res.text()}`);
+  }
+}

package/src/server/revalidate.ts

@@ -25,6 +25,7 @@
  */
 
 import { revalidatePath, revalidatePathPrefix, revalidateTag } from "./cache.js";
+import { purgeCdnByTags } from "./cdn.js";
 
 export interface RevalidateBody {
   /** Purge a single cached page path. */
@@ -64,7 +65,12 @@ export function applyRevalidate(
 
   if (path) revalidatePath(path);
   if (prefix) revalidatePathPrefix(prefix);
-  if (tags?.length) revalidateTag({ tags });
+  if (tags?.length) {
+    revalidateTag({ tags });
+    // Fire-and-forget: CDN purge is best-effort. In-process cache is already
+    // cleared above, so a CDN miss will just hit the origin and re-warm the edge.
+    void purgeCdnByTags(tags);
+  }
 
   return {
     revalidated: true,

package/src/ssr/html.ts

@@ -18,6 +18,13 @@ export interface HtmlShellOptions {
   headExtra?: string | undefined;
   /** Nonce for CSP inline scripts (optional). */
   nonce?: string | undefined;
+  /**
+   * Build ID for skew protection.
+   * Injected as `<meta name="alabjs-build-id">` so the client SPA router can
+   * detect a deployment change mid-session and trigger a hard reload instead
+   * of swapping components in-place with mismatched JS chunks.
+   */
+  buildId?: string | undefined;
 }
 
 /** Build the opening HTML fragment — everything up to and including `<div id="alabjs-root">`. */
@@ -31,6 +38,7 @@ export function htmlShellBefore(opts: HtmlShellOptions): string {
     layoutsJson,
     loadingFile,
     headExtra = "",
+    buildId,
   } = opts;
 
   const titleTag = metadata.title
@@ -76,6 +84,7 @@ export function htmlShellBefore(opts: HtmlShellOptions): string {
     <meta name="alabjs-search-params" content="${escAttr(searchParamsJson)}" />
     ${layoutsJson ? `<meta name="alabjs-layouts" content="${escAttr(layoutsJson)}" />` : ""}
     ${loadingFile ? `<meta name="alabjs-loading" content="${escAttr(loadingFile)}" />` : ""}
+    ${buildId ? `<meta name="alabjs-build-id" content="${escAttr(buildId)}" />` : ""}
     <link rel="stylesheet" href="/app/globals.css" />
     ${headExtra}
   </head>