Merge pull request #229 from JoviDeCroock/JoviDeCroock/not-found-api

Add a first-class not-found page instead of the catch-all workaround

Author: JoviDeCroock

.changeset/app-not-found-page.md

@@ -0,0 +1,33 @@
+---
+"@pracht/core": minor
+"@pracht/vite-plugin": minor
+"@pracht/cli": minor
+"create-pracht": patch
+---
+
+First-class not-found page: `defineApp({ notFound })` and `notFound()`.
+
+Until now the only way to ship a custom 404 was a trailing catch-all route
+(`route("/*", ...)`), which matches *every* URL — so it shadows requests for
+static assets and paths the app might serve later, shows up in typed routes,
+prefetching, speculation rules, and SSG path enumeration, and stops the client
+router from ever falling back to a document navigation for an unknown URL.
+
+- `defineApp({ notFound })` accepts a module ref or
+  `{ component, loader?, shell?, middleware?, hydration? }`. It is **not** a
+  route: it never participates in matching, so it runs only after matching (and,
+  on every first-party adapter, static-asset serving) has failed. It renders
+  through the normal pipeline — loader, shell, `head`, hydration — with a 404
+  status, and hydrates under a reserved route id.
+- `notFound(message?)` returns a `PrachtHttpError(404)` to throw from a loader
+  or middleware: `if (!post) throw notFound()`. The response is the app's
+  not-found page unless the route module exports its own `ErrorBoundary`, which
+  still wins. Shell-level error boundaries no longer intercept 404s once
+  `notFound` is configured.
+- Route-state (JSON) requests, non-GET/HEAD requests, and apps without a
+  `notFound` page keep their existing 404 behavior.
+- Pages router: `pages/404.tsx` is wired as the not-found page automatically and
+  removed from the route table, so `/404` is not a URL of its own.
+- `pracht dev` renders the app's own 404 page (instead of the dev-only route
+  table) when one is declared, matching production. `pracht inspect routes`,
+  the dev banner, and the `/_pracht` devtools page now report it.

docs/ADAPTERS.md

@@ -734,7 +734,12 @@ At the runtime level, an adapter also typically needs to:
    export a `markdown` source can respond from the framework.
 3. **Check for prerendered pages** -- SSG and ISG routes have HTML files on disk.
    For ISG, implement staleness checking.
-4. **Delegate dynamic requests** to `handlePrachtRequest()` from `pracht`
+4. **Delegate dynamic requests** to `handlePrachtRequest()` from `pracht`.
+   This ordering is what lets `defineApp({ notFound })` stay safe: the
+   not-found page only renders once matching *and* asset serving have missed,
+   so it can never shadow a real file. If the platform is configured to answer
+   misses itself (e.g. Cloudflare's `assets.not_found_handling`), that answer
+   wins and the app's not-found page never runs.
 5. **Convert the Web `Response`** back to the platform's response format
 6. **Provide a context factory** -- create app-level context from platform-specific
    inputs (env bindings, headers, etc.)

docs/ARCHITECTURE.md

@@ -703,8 +703,9 @@ Two ergonomics features are built in:
   dev-server URLs (`/src/routes/home.tsx`), which are joined onto the
   project root the dev middleware passes in (`server.config.root`).
 - **"Did you mean" wiring errors.** `resolveApp()` fails loudly when a
-  route or group references an unknown shell or middleware name (including
-  `api.middleware`), and `buildHref()` does the same for unknown route ids.
+  route, group, or the `notFound` page references an unknown shell or
+  middleware name (including `api.middleware`), and `buildHref()` does the
+  same for unknown route ids.
   The messages include a closest-match suggestion (small internal
   edit-distance helper in `name-suggestions.ts`, no dependency) and the
   full list of registered names, e.g.

docs/DATA_LOADING.md

@@ -138,40 +138,75 @@ Error boundaries compose: a route boundary catches route-level errors, while
 a shell boundary catches errors from any route inside that shell. If a route
 has no boundary, the error bubbles up to the shell, then to the global handler.
 
+404s take a different path when the app declares a
+[`notFound` page](#custom-404-pages): a route boundary still wins, but the
+not-found page takes over from there instead of the shell boundary. "Not
+found" is an outcome, not a failure.
+
 #### Custom 404 pages
 
-Throw `PrachtHttpError(404)` in a loader to trigger the route's error boundary
-with a 404 status. For a catch-all 404 page, add a wildcard route at the end
-of your manifest:
+Declare one page for "this URL has no content" and pracht uses it for both
+ways that happens — an unmatched URL, and a loader that cannot find what it
+was asked for:
 
 ```typescript
+// src/routes.ts
 export const app = defineApp({
+  shells: { public: () => import("./shells/public.tsx") },
+  notFound: {
+    component: () => import("./routes/not-found.tsx"),
+    shell: "public",
+  },
   routes: [
     // ... your routes
-    route("/:path*", () => import("./routes/not-found.tsx"), { render: "ssr" }),
   ],
 });
 ```
 
-```typescript
+```tsx
 // src/routes/not-found.tsx
-import { PrachtHttpError } from "@pracht/core";
+import { useLocation } from "@pracht/core";
 
-export function loader() {
-  throw new PrachtHttpError(404, "Page not found");
-}
+export function Component() {
+  const location = useLocation();
 
-export function ErrorBoundary() {
   return (
     <div>
       <h1>404</h1>
-      <p>This page doesn't exist.</p>
+      <p>No page lives at {location.pathname}.</p>
       <a href="/">Go home</a>
     </div>
   );
 }
 ```
 
+Inside a loader or middleware, `throw notFound()` — sugar for
+`new PrachtHttpError(404, message)`:
+
+```typescript
+import { notFound } from "@pracht/core";
+
+export async function loader({ params }: LoaderArgs) {
+  const post = await getPost(params.slug);
+  if (!post) throw notFound("Post not found");
+  return { post };
+}
+```
+
+The response is the `notFound` page with a 404 status — unless the route
+module exports its own `ErrorBoundary`, which stays the most specific handler
+and wins for that route. Shell-level error boundaries do not intercept 404s
+once `notFound` is configured; keep them for real failures.
+
+`notFound` is deliberately *not* a route: it never matches a URL, so it cannot
+shadow static assets the way a trailing `route("/*", ...)` does. See
+[ROUTING.md](ROUTING.md#not-found-page) for the full configuration and the
+exact matrix of when it renders.
+
+During a client-side navigation to a route whose loader throws a 404, the
+router falls back to a full document load so the server can render the
+not-found page with the correct status.
+
 #### Error sanitization
 
 Unexpected 5xx errors are sanitized by default in both SSR HTML and

docs/MCP.md

@@ -59,7 +59,7 @@ the server from the project directory.
 
 | Tool                  | Inputs                                                                                                              | Returns                                                                              |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `inspect_routes`      | `cwd?`                                                                                                              | Resolved page routes: path, id, render mode, hydration mode, prefetch strategy, speculation rules, shell, middleware, loader file. Unset options serialize as `null`. Same as `pracht inspect routes --json`. |
+| `inspect_routes`      | `cwd?`                                                                                                              | Resolved page routes: path, id, render mode, hydration mode, prefetch strategy, speculation rules, shell, middleware, loader file, plus `notFound` (the app-level 404 page, or `null`). Unset options serialize as `null`. Same as `pracht inspect routes --json`. |
 | `inspect_api`         | `cwd?`                                                                                                              | Resolved API routes: endpoint path, source file, exported HTTP methods, `hasDefaultHandler` (default catch-all export). Same as `pracht inspect api --json`. |
 | `inspect_build`       | `cwd?`                                                                                                              | Build metadata: adapter target, client entry URL, CSS/JS manifests (requires a prior `pracht build`). Same as `pracht inspect build --json`. |
 | `doctor`              | `cwd?`                                                                                                              | Wiring diagnostics with per-check status. Same as `pracht doctor --json`.            |

docs/REQUEST_FLOWS.md

@@ -488,18 +488,32 @@ request arrives
 ## Error paths
 
 ```
-SSR / SPA navigation — loader throws PrachtHttpError(404):
+SSR / SPA navigation — loader throws notFound() / PrachtHttpError(404):
 
   ── GET /blog/missing (route-state) ──►
   ◄── 404 application/json { error: { status: 404, message: "Not found" } } ──
 
-  Client: render ErrorBoundary({ error }) instead of Component
+  Client: render ErrorBoundary({ error }) instead of Component.
+  No boundary → full document load, so the server can render the
+  app's notFound page with a 404 status.
 
-SSR first load — loader throws PrachtHttpError(404):
+SSR first load — loader throws notFound() / PrachtHttpError(404):
 
   ── GET /blog/missing ──────────────────►
-  Server: loader throws → render ErrorBoundary to HTML string
-  ◄── 404 text/html (ErrorBoundary HTML with hydration state) ──────────────
+  Server: loader throws → route ErrorBoundary, else the app's notFound
+          page (if declared), else the shell boundary / plain text
+  ◄── 404 text/html (with hydration state) ─────────────────────────────────
+
+Unmatched URL — no route and no API route matches:
+
+  ── GET /nope ──────────────────────────►
+  (adapter already tried static assets and missed)
+  Server: no match → render defineApp({ notFound }) with status 404
+  ◄── 404 text/html (notFound page, hydrates under a reserved route id) ────
+
+  Without a notFound page:  ◄── 404 text/plain "Not found" ──
+  Route-state request:      ◄── 404 application/json { error } ──
+  Non-GET/HEAD:             ◄── 404 text/plain "Not found" ──
 
 Unexpected 5xx errors are sanitized in both HTML and JSON responses by default.
 Pass debugErrors: true to handlePrachtRequest() to expose raw error details.

docs/ROUTING.md

@@ -84,6 +84,7 @@ Top-level configuration:
 | `shells`     | `Record<string, ModuleRef>`              | Named shell modules — use `() => import("./path")` for IDE navigation |
 | `middleware` | `Record<string, ModuleRef>`              | Named middleware modules                                              |
 | `routes`     | `(RouteDefinition \| GroupDefinition)[]` | Route tree                                                            |
+| `notFound`   | `ModuleRef \| NotFoundConfig`            | Page rendered with a 404 status when nothing matches — see [Not-Found Page](#not-found-page) |
 
 ### `route(path, file, meta?)`
 
@@ -181,6 +182,83 @@ Matches `/docs/a/b/c` — the catch-all value is available in params.
 
 ---
 
+## Not-Found Page
+
+`defineApp({ notFound })` declares the page pracht renders — with a `404`
+status — when a request matches no route:
+
+```typescript
+export const app = defineApp({
+  shells: { public: () => import("./shells/public.tsx") },
+  notFound: {
+    component: () => import("./routes/not-found.tsx"),
+    shell: "public",
+  },
+  routes: [...],
+});
+```
+
+The shorthand `notFound: () => import("./routes/not-found.tsx")` takes the
+module ref directly. The full form accepts:
+
+| Field       | Type                            | Description                                       |
+| ----------- | ------------------------------- | ------------------------------------------------- |
+| `component` | `ModuleRef`                     | The page module (must live in the routes directory) |
+| `loader`    | `ModuleRef`                     | Optional separate loader module                   |
+| `shell`     | `string`                        | Named shell from `defineApp.shells`               |
+| `middleware`| `string[]`                      | Named middleware to run for this page             |
+| `hydration` | `"full" \| "islands" \| "none"` | Defaults to `"full"`, like a route                |
+
+The module is a normal route module: `Component`/`default`, an optional
+`loader`, `head`, and `headers` all work, and the page hydrates so its links
+and event handlers behave like any other page.
+
+### Why it is not a route
+
+A not-found page defined as a trailing catch-all — `route("/*", ...)` — matches
+*every* URL. That is the wrong shape for "nothing matched":
+
+- it shadows requests for static assets and any path the app might serve later,
+  which turns a missing `/logo.png` into an HTML page and hides genuine wiring
+  mistakes;
+- it appears in typed routes, prefetching, speculation rules, and SSG path
+  enumeration, none of which make sense for a 404;
+- the client router matches it too, so an unknown URL never falls back to a
+  document navigation.
+
+`notFound` sits outside the route table instead. It never matches a URL, so it
+runs only after route matching has failed — and, on every first-party adapter,
+after static-asset serving has failed too (Node checks `staticDir` first,
+Cloudflare asks the `ASSETS` binding first, Vercel's `handle: filesystem`
+precedes the function). Existing catch-all routes keep working unchanged; they
+simply match before the not-found page is ever considered.
+
+### When it renders
+
+| Request                                              | Response                                  |
+| ---------------------------------------------------- | ----------------------------------------- |
+| GET/HEAD document, no route matches                   | The `notFound` page, status 404           |
+| A loader or middleware throws `notFound()`            | The `notFound` page, status 404           |
+| The matched route exports an `ErrorBoundary`          | That boundary (most specific wins)        |
+| Route-state (`x-pracht-route-state-request`) request  | JSON `{ error: { status: 404 } }`         |
+| Non-GET/HEAD request to an unmatched path             | Plain-text `404`                          |
+| No `notFound` declared                                | Plain-text `404` (unchanged)              |
+
+See [DATA_LOADING.md](DATA_LOADING.md#custom-404-pages) for `notFound()` in
+loaders and how it interacts with error boundaries.
+
+Because the page is not a route, `pracht verify` constraints (which describe
+the route graph) do not apply to it, and it is never prerendered to a path of
+its own — it is always rendered on demand.
+
+### Pages router
+
+In `pagesDir` mode, `pages/404.tsx` is wired as the app's not-found page
+automatically. It is removed from the route table, so — unlike in Next.js —
+`/404` is not a URL of its own.
+
+---
+
 ## Typed Routes and Links
 
 Generate a type-safe route map from the same resolved app graph used by
@@ -676,8 +754,11 @@ clickable links. The page is self-contained HTML served by the dev middleware
 (`@pracht/core/dev-404`, same approach as the dev error overlay) and reloads
 automatically when a route is added.
 
-This page exists only in development:
+This page exists only in development, and only when the app has no 404 page of
+its own:
 
+- Apps that declare [`notFound`](#not-found-page) own their 404s — dev renders
+  that page, exactly as production does, and this page never appears.
 - Route-state (JSON) requests, non-document fetches, and non-GET methods keep
   their normal 404 behavior.
 - Apps that register a catch-all `route("*", ...)` match every path, so their

e2e/node-build.test.ts

@@ -79,6 +79,22 @@ test("pracht build emits a deployable Node server entry", async () => {
     expect(apiResponse.status).toBe(200);
     await expect(apiResponse.json()).resolves.toEqual({ status: "ok" });
 
+    // The app's notFound page renders for unmatched URLs, inside its shell.
+    const notFoundResponse = await fetch(`http://127.0.0.1:${port}/nope`);
+    expect(notFoundResponse.status).toBe(404);
+    expect(notFoundResponse.headers.get("content-type")).toContain("text/html");
+    expect(notFoundResponse.headers.get("x-pracht-shell")).toBe("public");
+    const notFoundHtml = await notFoundResponse.text();
+    expect(notFoundHtml).toContain("404 — page not found");
+    // It is not a route, so it is never prerendered to a path of its own.
+    expect(existsSync(resolve(exampleDir, "dist/client/nope/index.html"))).toBe(false);
+
+    // ...and it never shadows a static asset: the adapter serves those first.
+    const robotsResponse = await fetch(`http://127.0.0.1:${port}/robots.txt`);
+    expect(robotsResponse.status).toBe(200);
+    expect(robotsResponse.headers.get("content-type")).toContain("text/plain");
+    await expect(robotsResponse.text()).resolves.toContain("User-agent");
+
     const dashboardResponse = await fetch(`http://127.0.0.1:${port}/dashboard`, {
       headers: { cookie: "session=1" },
     });

e2e/not-found.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from "@playwright/test";
+
+// ---------------------------------------------------------------------------
+// App-level notFound page (`defineApp({ notFound })`). Runs against the
+// cloudflare example, which declares one — so the dev-only 404 page steps
+// aside and dev renders exactly what production renders.
+//
+// The point of the design is what it *cannot* do: the not-found page is not a
+// route, so it never matches a URL and therefore can never shadow a static
+// asset or a route registered later.
+// ---------------------------------------------------------------------------
+
+test("unmatched navigation renders the app notFound page with a 404 status", async ({ page }) => {
+  const response = await page.goto("/this/page/does/not/exist");
+
+  expect(response?.status()).toBe(404);
+  expect(response?.headers()["content-type"]).toContain("text/html");
+  await expect(page.locator("#not-found h1")).toContainText("404");
+  await expect(page.locator("#requested-path")).toHaveText("/this/page/does/not/exist");
+  // Rendered inside the configured shell, like any other page.
+  await expect(page.locator(".public-shell header")).toBeVisible();
+});
+
+test("the notFound page hydrates and navigates like a normal page", async ({ page }) => {
+  await page.goto("/nope");
+  await page.locator("html[data-pracht-hydrated]").waitFor();
+
+  await page.click("#not-found a");
+  await expect(page.locator("h1")).not.toContainText("404");
+  expect(new URL(page.url()).pathname).toBe("/");
+});
+
+test("static assets are served instead of the notFound page", async ({ request }) => {
+  const response = await request.get("/robots.txt");
+
+  expect(response.status()).toBe(200);
+  expect(await response.text()).toContain("User-agent");
+});
+
+test("existing routes are unaffected", async ({ page }) => {
+  const response = await page.goto("/pricing");
+  expect(response?.status()).toBe(200);
+});
+
+test("route-state requests for unmatched paths stay JSON", async ({ request }) => {
+  const response = await request.get("/nope", {
+    headers: { accept: "*/*", "x-pracht-route-state-request": "1" },
+  });
+
+  expect(response.status()).toBe(404);
+  expect(response.headers()["content-type"]).toContain("application/json");
+  expect(await response.text()).not.toContain("<h1>");
+});

examples/basic/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /