1.4.0: not_found, server-only response options, compression

- Server functions can return not_found: true to render the 404 page
  with status 404.
- Page components and window.__PAGE_PROPS__ (and HMR updates) only get
  props, query, url and error. response_options, redirect, cache settings
  and res_transform stay on the server, so cookies and private headers no
  longer end up in the HTML. BunextPageProps is narrowed to match
  (breaking for code that read server-only fields from component props).
- response_options headers go through a Headers object, so repeated
  headers such as several Set-Cookie survive.
- Redirects: status_code wins over permanent; response_options headers
  and res_transform apply to redirects too.
- Gzip for compressible text responses; compress: false to turn it off.
- Files the router matches but never bundles (.server.ts, __root,
  excluded paths and directories) return 404 instead of looping through
  dev rebuild retries.
- Missing public files return 404 rather than 403, so dotted page paths
  like /users/john.doe fall through to pages again.
- importFresh detects rewrites within the filesystem's mtime granularity.
- README: self-hosted React (not esm.sh), snake_case option names, static
  file serving, cache headers, the new options.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dist/utils/compress-response.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Gzips `res` when the client accepts gzip and the body is compressible
+ * text. Streams (no buffering), so it is safe for large and streamed
+ * responses. Responses that are already encoded, ranged, bodiless or
+ * event streams pass through untouched.
+ */
+export default function compressResponse(req: Request, res: Response): Response;

dist/utils/compress-response.js

@@ -0,0 +1,45 @@
+const COMPRESSIBLE = /^(text\/(?!event-stream)|application\/(javascript|json|xml|manifest\+json|ld\+json|rss\+xml|atom\+xml)|image\/svg\+xml)/i;
+/** Smaller bodies aren't worth the gzip overhead. */
+const MIN_SIZE = 1024;
+/**
+ * Gzips `res` when the client accepts gzip and the body is compressible
+ * text. Streams (no buffering), so it is safe for large and streamed
+ * responses. Responses that are already encoded, ranged, bodiless or
+ * event streams pass through untouched.
+ */
+export default function compressResponse(req, res) {
+    if (!res.body || req.method === "HEAD")
+        return res;
+    if (res.status < 200 || res.status === 204 || res.status === 206) {
+        return res;
+    }
+    if (res.headers.has("Content-Encoding"))
+        return res;
+    if (!/\bgzip\b/i.test(req.headers.get("Accept-Encoding") || "")) {
+        return res;
+    }
+    if (!COMPRESSIBLE.test(res.headers.get("Content-Type") || ""))
+        return res;
+    if (/\bno-transform\b/i.test(res.headers.get("Cache-Control") || "")) {
+        return res;
+    }
+    const length = Number(res.headers.get("Content-Length"));
+    if (length && length < MIN_SIZE)
+        return res;
+    // Copy: headers of fetch()/Response.redirect responses are immutable
+    const headers = new Headers(res.headers);
+    headers.set("Content-Encoding", "gzip");
+    headers.delete("Content-Length");
+    const vary = headers.get("Vary");
+    if (!vary) {
+        headers.set("Vary", "Accept-Encoding");
+    }
+    else if (!/\b(accept-encoding|\*)\b/i.test(vary)) {
+        headers.set("Vary", `${vary}, Accept-Encoding`);
+    }
+    return new Response(res.body.pipeThrough(new CompressionStream("gzip")), {
+        status: res.status,
+        statusText: res.statusText,
+        headers,
+    });
+}

dist/utils/grab-bunext-public-url-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * # URL path the dist `public` directory is served at
+ * Its path relative to the project root, e.g. `/.bunext/public`. Bundle
+ * paths in the bundler maps are project-relative, so `/${path}` is their
+ * URL. Kept out of `grabDirNames()`: `init` creates every path listed there.
+ */
+export default function grabBunextPublicUrlPath(): string;

dist/utils/grab-bunext-public-url-path.js

@@ -0,0 +1,15 @@
+import path from "path";
+import grabDirNames from "./grab-dir-names";
+/**
+ * # URL path the dist `public` directory is served at
+ * Its path relative to the project root, e.g. `/.bunext/public`. Bundle
+ * paths in the bundler maps are project-relative, so `/${path}` is their
+ * URL. Kept out of `grabDirNames()`: `init` creates every path listed there.
+ */
+export default function grabBunextPublicUrlPath() {
+    const { ROOT_DIR, BUNEXT_PUBLIC_DIR } = grabDirNames();
+    return `/${path
+        .relative(ROOT_DIR, BUNEXT_PUBLIC_DIR)
+        .split(path.sep)
+        .join("/")}`;
+}

dist/utils/grab-client-page-props.d.ts

@@ -0,0 +1,11 @@
+import type { BunextPageModuleServerReturn, BunextPageProps } from "../types";
+/**
+ * The part of a server function's result that is sent to the browser (as
+ * `window.__PAGE_PROPS__` and in HMR updates) and passed to the page and
+ * root components.
+ *
+ * An allowlist: everything else (`response_options` with its headers and
+ * cookies, `redirect`, cache settings, `res_transform`) is server-only and
+ * must not end up in the HTML.
+ */
+export default function grabClientPageProps(serverRes?: BunextPageModuleServerReturn | null): BunextPageProps;

dist/utils/grab-client-page-props.js

@@ -0,0 +1,23 @@
+/**
+ * The part of a server function's result that is sent to the browser (as
+ * `window.__PAGE_PROPS__` and in HMR updates) and passed to the page and
+ * root components.
+ *
+ * An allowlist: everything else (`response_options` with its headers and
+ * cookies, `redirect`, cache settings, `res_transform`) is server-only and
+ * must not end up in the HTML.
+ */
+export default function grabClientPageProps(serverRes) {
+    if (!serverRes)
+        return {};
+    const client_props = {};
+    if (serverRes.props !== undefined)
+        client_props.props = serverRes.props;
+    if (serverRes.query !== undefined)
+        client_props.query = serverRes.query;
+    if (serverRes.url !== undefined)
+        client_props.url = serverRes.url;
+    if (serverRes.error !== undefined)
+        client_props.error = serverRes.error;
+    return client_props;
+}

dist/utils/grab-dir-names.d.ts

@@ -31,4 +31,11 @@ export type DirNames = {
     BUILD_INFO_JSON: string;
     PAGE_LASTMOD_JSON: string;
 };
+/**
+ * # Project and artifact paths
+ * The dist directory comes from `BUNEXT_DIST_DIR`, which `setupDistDir()`
+ * sets from `--dist-dir` / `dist_dir` in the config. Call this where the
+ * paths are used, not at module load: a module loaded before
+ * `setupDistDir()` runs would keep the default directory.
+ */
 export default function grabDirNames(): DirNames;

dist/utils/grab-dir-names.js

@@ -1,14 +1,33 @@
 import path from "path";
+import { DistDirEnvName, resolveDistDir } from "./grab-dist-dir";
+let cached;
+/**
+ * # Project and artifact paths
+ * The dist directory comes from `BUNEXT_DIST_DIR`, which `setupDistDir()`
+ * sets from `--dist-dir` / `dist_dir` in the config. Call this where the
+ * paths are used, not at module load: a module loaded before
+ * `setupDistDir()` runs would keep the default directory.
+ */
 export default function grabDirNames() {
     if (global.BUNEXT_DIR_NAMES)
         return global.BUNEXT_DIR_NAMES;
+    const key = `${process.cwd()}\0${process.env[DistDirEnvName] || ""}`;
+    if (cached?.key !== key) {
+        cached = { key, dir_names: computeDirNames() };
+    }
+    return cached.dir_names;
+}
+function computeDirNames() {
     const ROOT_DIR = process.cwd();
     const SRC_DIR = path.join(ROOT_DIR, "src");
     const PAGES_DIR = path.join(SRC_DIR, "pages");
     const API_DIR = path.join(PAGES_DIR, "api");
     const PUBLIC_DIR = path.join(ROOT_DIR, "public");
     const CONFIG_FILE = path.join(ROOT_DIR, "bunext.config.ts");
-    const BUNX_CWD_DIR = path.resolve(ROOT_DIR, ".bunext");
+    const BUNX_CWD_DIR = resolveDistDir({
+        dist_dir: process.env[DistDirEnvName],
+        root_dir: ROOT_DIR,
+    });
     const BUNX_CWD_MODULE_CACHE_DIR = path.resolve(BUNX_CWD_DIR, "module-cache");
     const BUNX_CWD_PAGES_REWRITE_DIR = path.resolve(BUNX_CWD_DIR, "pages");
     const BUNX_TMP_DIR = path.resolve(BUNX_CWD_DIR, ".tmp");

dist/utils/grab-dist-dir.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Env var holding the dist directory. The CLI sets it from `--dist-dir` or
+ * `dist_dir` in bunext.config.ts before any other module loads: most
+ * modules read the directory names once, at import time. Child processes
+ * (dev/start servers) inherit it.
+ */
+export declare const DistDirEnvName = "BUNEXT_DIST_DIR";
+type Params = {
+    dist_dir?: string;
+    root_dir: string;
+};
+/**
+ * # Resolve the dist directory
+ * Returns the absolute path of the build artifact directory. `dist_dir` is
+ * relative to the project root (or absolute) and must sit inside it: the
+ * dev watcher only watches the project root, and checks it is alive through
+ * a probe file in the dist directory. Its relative path is also the URL
+ * path of the client bundles, so it is limited to URL-safe characters.
+ */
+export declare function resolveDistDir({ dist_dir, root_dir }: Params): string;
+export {};

dist/utils/grab-dist-dir.js

@@ -0,0 +1,51 @@
+import path from "path";
+import AppNames from "./grab-app-names";
+/**
+ * Env var holding the dist directory. The CLI sets it from `--dist-dir` or
+ * `dist_dir` in bunext.config.ts before any other module loads: most
+ * modules read the directory names once, at import time. Child processes
+ * (dev/start servers) inherit it.
+ */
+export const DistDirEnvName = "BUNEXT_DIST_DIR";
+const ReservedDirs = ["src", "public", "node_modules"];
+/**
+ * # Resolve the dist directory
+ * Returns the absolute path of the build artifact directory. `dist_dir` is
+ * relative to the project root (or absolute) and must sit inside it: the
+ * dev watcher only watches the project root, and checks it is alive through
+ * a probe file in the dist directory. Its relative path is also the URL
+ * path of the client bundles, so it is limited to URL-safe characters.
+ */
+export function resolveDistDir({ dist_dir, root_dir }) {
+    const resolved = path.resolve(root_dir, dist_dir?.trim() || AppNames.defaultDistDir);
+    if (!isInsideDir(resolved, root_dir)) {
+        throw new Error(`Invalid dist directory \`${dist_dir}\`: it must be a directory ` +
+            `inside the project root (${root_dir}).`);
+    }
+    const url_path = path
+        .relative(root_dir, resolved)
+        .split(path.sep)
+        .join("/");
+    if (!/^[\w.\-\/]+$/.test(url_path)) {
+        throw new Error(`Invalid dist directory \`${dist_dir}\`: use only letters, ` +
+            `digits, \`.\`, \`_\`, \`-\` and \`/\`.`);
+    }
+    for (const reserved of ReservedDirs) {
+        const reserved_dir = path.join(root_dir, reserved);
+        if (resolved === reserved_dir || isInsideDir(resolved, reserved_dir)) {
+            throw new Error(`Invalid dist directory \`${dist_dir}\`: it can't be ` +
+                `\`${reserved}/\` or inside it.`);
+        }
+    }
+    return resolved;
+}
+/**
+ * Whether `target` is strictly inside `dir` (not `dir` itself)
+ */
+function isInsideDir(target, dir) {
+    const relative = path.relative(dir, target);
+    return (Boolean(relative) &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}

dist/utils/grab-redirect-response.d.ts

@@ -0,0 +1,13 @@
+import type { BunextPageModuleServerReturn, BunxRouteParams } from "../types";
+type Params = {
+    serverRes: BunextPageModuleServerReturn;
+    routeParams?: BunxRouteParams;
+};
+/**
+ * Builds the redirect Response for a server function that returned
+ * `redirect`. An explicit `status_code` wins; otherwise `permanent` picks
+ * 301, and the default is 302. Headers from `response_options` (e.g. a
+ * Set-Cookie on login) and `res_transform` apply to the redirect too.
+ */
+export default function grabRedirectResponse({ serverRes, routeParams, }: Params): Promise<Response>;
+export {};

dist/utils/grab-redirect-response.js

@@ -0,0 +1,21 @@
+/**
+ * Builds the redirect Response for a server function that returned
+ * `redirect`. An explicit `status_code` wins; otherwise `permanent` picks
+ * 301, and the default is 302. Headers from `response_options` (e.g. a
+ * Set-Cookie on login) and `res_transform` apply to the redirect too.
+ */
+export default async function grabRedirectResponse({ serverRes, routeParams, }) {
+    const redirect = serverRes.redirect;
+    const status = redirect.status_code || (redirect.permanent ? 301 : 302);
+    const headers = new Headers(serverRes.response_options?.headers);
+    headers.set("Location", redirect.destination);
+    const res = new Response(null, { status, headers });
+    // Same precedence as HTML responses
+    if (routeParams?.res_transform) {
+        return await routeParams.res_transform(res);
+    }
+    if (serverRes.res_transform) {
+        return await serverRes.res_transform(res);
+    }
+    return res;
+}

dist/utils/import-fresh.js

@@ -2,8 +2,9 @@ import { existsSync, statSync } from "fs";
 import path from "path";
 import isDevelopment from "./is-development";
 /**
- * File path -> mtime of the version currently held in Bun's module
- * registry (dev only).
+ * File path -> version (mtime, size, inode) of the module currently held
+ * in Bun's module registry (dev only). mtime alone misses rewrites within
+ * the filesystem's timestamp granularity (several ms on ext4).
  */
 const loaded_versions = new Map();
 /**
@@ -20,18 +21,19 @@ export default async function importFresh(file_path) {
     if (!isDevelopment()) {
         return import(file_path);
     }
-    let mtime;
+    let version;
     try {
-        mtime = statSync(file_path).mtimeMs;
+        const stat = statSync(file_path);
+        version = `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
     }
     catch { }
     if (loaded_versions.has(file_path) &&
-        loaded_versions.get(file_path) !== mtime) {
+        loaded_versions.get(file_path) !== version) {
         evictModule(file_path);
     }
     try {
         const mod = await import(file_path);
-        loaded_versions.set(file_path, mtime);
+        loaded_versions.set(file_path, version);
         return mod;
     }
     catch (error) {

dist/utils/is-routable-page.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a file matched by the FileSystemRouter is actually a page.
+ *
+ * `Bun.FileSystemRouter` routes every file under `src/pages`, including
+ * ones the bundler never builds: `.server.ts` companions, the `__root`
+ * layout, tests, and paths excluded by `pages_exclude_patterns` (or inside
+ * an excluded directory). Requests for those must 404 rather than wait for
+ * a bundle that will never exist. Mirrors the rules in `grabAllPages`.
+ */
+export default function isRoutablePage(file_path: string): boolean;

dist/utils/is-routable-page.js

@@ -0,0 +1,39 @@
+import path from "path";
+import AppNames from "./grab-app-names";
+import checkExcludedPatterns from "./check-excluded-patterns";
+import grabDirNames from "./grab-dir-names";
+/**
+ * Whether a file matched by the FileSystemRouter is actually a page.
+ *
+ * `Bun.FileSystemRouter` routes every file under `src/pages`, including
+ * ones the bundler never builds: `.server.ts` companions, the `__root`
+ * layout, tests, and paths excluded by `pages_exclude_patterns` (or inside
+ * an excluded directory). Requests for those must 404 rather than wait for
+ * a bundle that will never exist. Mirrors the rules in `grabAllPages`.
+ */
+export default function isRoutablePage(file_path) {
+    const { PAGES_DIR } = grabDirNames();
+    const file_name = path.basename(file_path);
+    if (/\.server\.(t|j)sx?$/.test(file_name))
+        return false;
+    if (/\.test\.(t|j)sx?$/.test(file_name))
+        return false;
+    if (/__tests__/.test(file_path))
+        return false;
+    if (file_name.match(new RegExp(AppNames["RootPagesComponentName"]))) {
+        return false;
+    }
+    // grabAllPages skips an excluded directory without looking inside it,
+    // so check every directory between PAGES_DIR and the file as well.
+    const relative = path.relative(PAGES_DIR, file_path);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return !checkExcludedPatterns({ path: file_path });
+    }
+    let current = PAGES_DIR;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        if (checkExcludedPatterns({ path: current }))
+            return false;
+    }
+    return true;
+}

dist/utils/not-found-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thrown to render the 404 page (with status 404) instead of the matched
+ * page: for unmatched or non-routable paths, and when a page's server
+ * function returns `not_found: true`.
+ */
+export default class NotFoundError extends Error {
+    status: number;
+    constructor(message: string);
+}

dist/utils/not-found-error.js

@@ -0,0 +1,12 @@
+/**
+ * Thrown to render the 404 page (with status 404) instead of the matched
+ * page: for unmatched or non-routable paths, and when a page's server
+ * function returns `not_found: true`.
+ */
+export default class NotFoundError extends Error {
+    status = 404;
+    constructor(message) {
+        super(message);
+        this.name = "NotFoundError";
+    }
+}

dist/utils/page-path-transform.js

@@ -1,11 +1,12 @@
 import path from "path";
 import grabDirNames from "./grab-dir-names";
-const { ROOT_DIR, BUNX_CWD_PAGES_REWRITE_DIR } = grabDirNames();
+const { ROOT_DIR } = grabDirNames();
 /**
  * # Transform a page path to the destination
  * path in the .bunext directory
  */
 export default function pagePathTransform({ page_path }) {
+    const { BUNX_CWD_PAGES_REWRITE_DIR } = grabDirNames();
     const page_path_relative_dir = page_path
         .replace(ROOT_DIR, "")
         .replace(/\/src\/pages/, "");

dist/utils/resolve-public-file.d.ts

@@ -0,0 +1,15 @@
+type Return = {
+    status: 200;
+    file_path: string;
+} | {
+    status: 403 | 404;
+};
+/**
+ * Maps a URL path onto a file in `dir`, in this order:
+ * - `..` segments (encoded or not) are resolved against `/`, so they
+ *   can never climb above `dir`; the 403 check is a second guard
+ * - 404 if there is no such file (so callers can fall through to pages)
+ * - 403 if a symlink points outside `dir`
+ */
+export default function resolvePublicFile(dir: string, url_path: string): Return;
+export {};

dist/utils/resolve-public-file.js

@@ -0,0 +1,31 @@
+import { existsSync, statSync } from "fs";
+import path from "path";
+import isSafePath from "./is-safe-path";
+/**
+ * Maps a URL path onto a file in `dir`, in this order:
+ * - `..` segments (encoded or not) are resolved against `/`, so they
+ *   can never climb above `dir`; the 403 check is a second guard
+ * - 404 if there is no such file (so callers can fall through to pages)
+ * - 403 if a symlink points outside `dir`
+ */
+export default function resolvePublicFile(dir, url_path) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(url_path);
+    }
+    catch {
+        return { status: 404 };
+    }
+    const root = path.resolve(dir);
+    const file_path = path.resolve(root, "." + path.posix.join("/", decoded));
+    if (file_path !== root && !file_path.startsWith(root + path.sep)) {
+        return { status: 403 };
+    }
+    if (!existsSync(file_path) || !statSync(file_path).isFile()) {
+        return { status: 404 };
+    }
+    if (!isSafePath({ filePath: file_path, allowedDir: root })) {
+        return { status: 403 };
+    }
+    return { status: 200, file_path };
+}

dist/utils/write-logs.js

@@ -1,8 +1,8 @@
 import { writeFileSync } from "fs";
 import grabDirNames from "./grab-dir-names";
 import path from "path";
-const { BUNX_LOGS_DIR } = grabDirNames();
 export default function writeLogs(log) {
+    const { BUNX_LOGS_DIR } = grabDirNames();
     try {
         const now = Date.now();
         let new_log_name = `${now}`;