@wular/pnext 0.0.4 → 0.0.7

package/README.md

@@ -8,6 +8,8 @@
 
 ## Getting started
 
+> pnext requires [Bun](https://bun.sh/get) - make sure it is installed first.
+
 A new app:
 
 ```sh
@@ -22,11 +24,13 @@ bunx @wular/pnext migrate
 
 Or by hand: `bun add -d @wular/pnext`, then `pnext dev`.
 
+[Getting Started](./reference/getting-started.md) walks through all of it, from first page to build.
+
 ## Incremental by design
 
-Server-rendered pages ship **0 KB** of JavaScript, or **~1 KB gzip** if you want client-side navigation and prefetching. Interactive pages hydrate on Preact for **~7.5 KB** of framework, **~12.5 KB** with React compatibility. And everything is instant: the first page in dev renders **11–13.5× faster** than Next's on **3.4–3.8× less memory**, and production builds run **7–10.5× faster**. See [Performance](./reference/performance.md).
+Server-rendered pages ship **0 KB** of JavaScript, or **~1 KB gzip** if you want client-side navigation and prefetching. Interactive pages hydrate on Preact for **~7.5 KB** of framework, **~12.5 KB** with React compatibility. Everything is instant, the first page in dev renders **10–12× faster** than Next.js on **3.5–4× less memory**, and production builds run **7–9× faster**. See [Performance](./reference/performance.md).
 
-Core pnext is pure Preact. `compat.react` runs React components and libraries on it, and `compat.next` runs a whole Next.js App Router app unchanged. Start anywhere on that ladder and move when it suits you. The App Router compatibility is validated against Next's own test suite (4,400+ assertions passing). The `pages/` folder is not supported, and neither are private internal utilities of Next.js or React. See [Compatibility](./reference/compat.md).
+Core pnext is pure Preact. `compat.react` runs React components and libraries on it, and `compat.next` runs a whole Next.js App Router app unchanged. Start anywhere on that ladder and move when it suits you. The App Router compatibility is validated against Next's own test suite (4,400+ assertions passing). The `pages/` folder or private internal utilities of Next.js or React are mostly not supported. See [Compatibility](./reference/compat.md).
 
 ## A quick tour
 
@@ -36,17 +40,17 @@ Routes live in `app/`. A `page.tsx` is a Server Component by default. It runs on
 
 ```tsx
 // app/posts/[id]/page.tsx
-import type { PageProps } from "#gen/app/posts/[id]/page";
+import type { PageProps } from '#gen/app/posts/[id]/page'
 
 export default async function Page({ params }: PageProps) {
-  const { id } = await params;
-  const post = await db.post.findUnique({ where: { id } });
+  const { id } = await params
+  const post = await db.post.findUnique({ where: { id } })
   return (
     <article>
       <h1>{post.title}</h1>
       <p>{post.body}</p>
     </article>
-  );
+  )
 }
 ```
 
@@ -58,12 +62,14 @@ Mark a component with `"use client"` where you need state, effects, or event han
 
 ```tsx
 // app/counter.tsx
-"use client";
-import { useState } from "preact/hooks";
+'use client'
+import { useState } from 'preact/hooks'
 
 export function Counter({ initial }: { initial: number }) {
-  const [count, setCount] = useState(initial);
-  return <button onClick={() => setCount(count + 1)}>Count {count}</button>;
+  const [count, setCount] = useState(initial)
+  return (
+    <button onClick={() => setCount(count + 1)}>Count {count}</button>
+  )
 }
 ```
 
@@ -74,14 +80,14 @@ Client Components hydrate on Preact for ~7.5 KB of framework, or ~12.5 KB with [
 Wrap slow server work in `<Suspense>`. The shell streams immediately and the content follows when it's ready:
 
 ```tsx
-import { Suspense } from "@wular/pnext";
+import { Suspense } from '@wular/pnext'
 
 export default function Page() {
   return (
     <Suspense fallback={<p>Loading comments…</p>}>
       <Comments />
     </Suspense>
-  );
+  )
 }
 ```
 
@@ -92,20 +98,20 @@ A `route.ts` file is an HTTP handler:
 ```ts
 // app/api/users/route.ts
 export async function GET(request: NextRequest) {
-  return Response.json(await listUsers());
+  return Response.json(await listUsers())
 }
 ```
 
 - `proxy.ts` runs before route matching.
 - `loading.tsx`, `error.tsx`, and `not-found.tsx` define per-segment fallbacks.
-- `pnext build` emits static HTML for routes that never read the request, and a server for the ones that do. `pnext start` serves it.
+- `pnext build` makes the production build and `pnext start` serves it. Routes that never read the request are prerendered to static HTML.
 
 ## Learn more
 
 Apps are file-routed from `app/`: `page.tsx` and `layout.tsx` are Server Components, `route.ts` files are HTTP handlers, `public/` is served from `/`. The reference covers the rest:
 
-- [Overview](./reference/overview.md)
-- [Dev server](./reference/dev.md)
+- [Getting Started](./reference/getting-started.md)
+- [Development](./reference/dev.md)
 - [Routing](./reference/routing.md)
 - [Navigation](./reference/navigation.md)
 - [Rendering](./reference/rendering.md)

package/bin/pnext

@@ -1,5 +1,10 @@
 #!/bin/sh
 
+if ! command -v bun >/dev/null 2>&1; then
+  echo "pnext requires Bun. Install it from https://bun.sh/get" >&2
+  exit 1
+fi
+
 script=$0
 
 # `dirname` is an external binary and `$(...)` forks a subshell, so spelling this
@@ -47,7 +52,7 @@ fi
 # instead of showing "bun". The kernel takes the process name from the exec'd
 # file's basename; argv0 tricks like `exec -a` never reach it.
 #
-# The cached names are hardlinks of a bun binary (see src/cli/named-bin.ts), so
+# The cached names are hardlinks of a bun binary (see src/cli/boot/named-bin.ts), so
 # `-ef` — same device and inode — proves a candidate is *this* bun and never
 # execs a stale one left by an earlier version. Resolving it here in sh instead
 # of asking named-bin.ts saves a whole bun process per command; on a miss we run

package/config/lint/base.js

@@ -1,10 +1,10 @@
-import * as path from 'node:path';
-import { includeIgnoreFile } from '@eslint/compat';
+import * as path from 'node:path'
+import { includeIgnoreFile } from '@eslint/compat'
 // @ts-ignore
-import eslint from '@eslint/js';
-import importPlugin from 'eslint-plugin-import';
-import turboPlugin from 'eslint-plugin-turbo';
-import tseslint from 'typescript-eslint';
+import eslint from '@eslint/js'
+import importPlugin from 'eslint-plugin-import'
+import turboPlugin from 'eslint-plugin-turbo'
+import tseslint from 'typescript-eslint'
 
 export default tseslint.config(
   includeIgnoreFile(path.join(import.meta.dirname, '../../.gitignore')),
@@ -45,4 +45,4 @@ export default tseslint.config(
     linterOptions: { reportUnusedDisableDirectives: true },
     languageOptions: { parserOptions: { projectService: true } },
   },
-);
+)

package/config/ts/base.json

@@ -6,9 +6,7 @@
     "esModuleInterop": true,
     "incremental": false,
     "isolatedModules": true,
-    "lib": [
-      "ESNext"
-    ],
+    "lib": ["ESNext"],
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "moduleDetection": "force",
@@ -23,4 +21,4 @@
     "allowJs": true,
     "noEmit": true
   }
-}
+}

package/config/ts/react.json

@@ -3,11 +3,7 @@
   "display": "React Library",
   "extends": "./base.json",
   "compilerOptions": {
-    "lib": [
-      "DOM",
-      "DOM.Iterable",
-      "ESNext"
-    ],
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
     "jsx": "react-jsx"
   }
-}
+}

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.4",
+  "version": "0.0.7",
+  "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {
     "pnext": "bin/pnext"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/muzam1l/pnext.git"
+  },
+  "homepage": "https://github.com/muzam1l/pnext",
+  "bugs": {
+    "url": "https://github.com/muzam1l/pnext/issues"
+  },
+  "keywords": [
+    "react",
+    "preact",
+    "framework",
+    "ssr",
+    "server-components",
+    "bun",
+    "nextjs"
+  ],
   "files": [
     "bin",
     "config",
@@ -27,7 +45,8 @@
     "./config/*": "./config/*"
   },
   "scripts": {
-    "lint": "bun scripts/check-compat-boundary.ts && eslint . --max-warnings 0 && tsc --noEmit",
+    "lint": "bun scripts/check-compat-boundary.ts && prettier --check . && eslint . --max-warnings 0 && tsc --noEmit",
+    "format": "prettier --write .",
     "bench": "bun bench/run.ts",
     "clean": "rm -rf .turbo .pnext node_modules",
     "prepublishOnly": "bun run lint",
@@ -53,8 +72,10 @@
     "@eslint/js": "^9.38.0",
     "@types/bun": "^1.3.0",
     "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-turbo": "^2.5.8",
+    "prettier": "^3.9.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.2"
   },

package/reference/compat.md

@@ -1,6 +1,6 @@
 # Compatibility
 
-pnext is Next.js-shaped. With `compat.next` on, App Router apps behave the way they do in Next: the `next/*` module surface, `next.config.js`, server actions, metadata, `proxy`/`middleware`, `'use cache'`, the `/_next/image` optimizer, and the `next/navigation` router. That is validated by running Next.js's own test suite against pnext rather than by hand-written parity claims.
+pnext is Next.js-shaped. With `compat.next` on, App Router apps behave the way they do in Next: the `next/*` module surface, `next.config.js`, server actions, metadata, proxy and middleware, `'use cache'`, the `/_next/image` optimizer, and the `next/navigation` router. That is validated by running Next.js's own test suite against pnext, with 4,400+ assertions passing, rather than by hand-written parity claims.
 
 ```ts
 export default {
@@ -9,55 +9,120 @@ export default {
     next: true, // the next/* surface + next.config.js; implies react
     reactCompiler: true, // React Compiler for React-style Client Components; implies react
   },
-};
+}
 ```
 
-`compat.react` aliases `react`, `react-dom`, `react-dom/client`, `react-dom/server`, `react/jsx-runtime`, `react/jsx-dev-runtime`, and `react/compiler-runtime` onto Preact-backed shims. `react`'s `cache()` maps to pnext's request cache on the server.
+`compat.react` aliases `react`, `react-dom`, `react-dom/client`, `react-dom/server`, `react/jsx-runtime`, `react/jsx-dev-runtime`, and `react/compiler-runtime` onto Preact-backed shims. React's `cache()` maps to pnext's request cache on the server. Importing `next/*` or `react` without the matching mode is a build error that names the flag to enable.
 
-Importing `next/*` or `react` without the matching compat mode is a build error naming the flag to enable.
+To turn Next compatibility on without a config file, set `PNEXT_COMPAT=next`. See [Environment Variables](./env.md).
 
-Everything below is a place pnext deliberately does not match Next. It is the whole list.
+## Migrating a Next.js app
 
-## Preact, not React
+```sh
+bunx @wular/pnext migrate --dry-run
+bunx @wular/pnext migrate
+```
+
+Migration rewrites `package.json` and `tsconfig.json`, and creates a `pnext.config.ts` with `compat.next` enabled. It reports on your app source but never edits it.
+
+## What differs from Next
+
+These are the places pnext deliberately does not match Next. Read them before migrating. Together with the caveats in the feature notes below, this is the whole list.
 
-`react-dom/server`'s streaming renderers (`renderToReadableStream`, `renderToPipeableStream`) throw; the synchronous `renderToString`/`renderToStaticMarkup` work. Client components run on Preact's reconciler, so code reaching into React internals is out of scope.
+### Preact, not React
+
+The streaming renderers from `react-dom/server`, `renderToReadableStream` and `renderToPipeableStream`, throw. The synchronous `renderToString` and `renderToStaticMarkup` work. Client components run on Preact's reconciler, so code reaching into React internals is out of scope.
 
 Direct Preact imports and Preact Signals need no compat and produce smaller bundles than `preact/compat`.
 
-## No Flight payload
+### No Flight payload
+
+Soft navigation and server-action responses carry HTML, not a React Flight stream. Streaming, refresh, and revalidation-driven updates all work. Consuming the RSC payload as a wire format does not.
 
-Soft navigation and server-action responses carry HTML, not a React Flight stream. Streaming, `refresh()`, and revalidation-driven updates all work; consuming the RSC payload as a wire format does not.
+Server-rendered JSX can cross into a Client Component as `children` or through any other prop, including nested in arrays and plain objects. Both stay server-rendered static HTML and ship no code, as in Next. Elements inside `Map` and `Set` props are the one shape that throws.
 
-Server-rendered JSX crosses into a Client Component as `children` or through any other prop (including nested in arrays and plain objects) — both stay server-rendered static HTML and ship no code, like in Next. Elements inside `Map`/`Set` props are the one shape that throws.
+### Pages Router is emulated
 
-## Pages Router is emulated
+A `pages/` directory is materialized onto App Router routes, so `getStaticProps` and `getServerSideProps` pages and `pages/api` handlers run. `_app`, `_document`, and `_error` are ignored. `next/head` renders nothing, so use the metadata exports instead. `next/router` maps onto the app router where the concepts line up and no-ops elsewhere.
 
-A `pages/` directory is materialized onto App Router routes, so `getStaticProps`/`getServerSideProps` pages and `pages/api` handlers run. `_app`, `_document`, and `_error` are ignored. `next/head` renders nothing — use the metadata exports. `next/router` maps onto the app router where the concepts line up and no-ops elsewhere.
+### No webpack or Turbopack
 
-## No webpack or Turbopack
+esbuild is the only bundler. A `webpack(config)` function in `next.config.js` is not executed, and pnext warns once at config load when one is present. Loader chains from `turbopack.rules`, plus `turbopack.resolveAlias`, `transpilePackages`, `modularizeImports`, and `optimizePackageImports`, are re-implemented on esbuild directly.
 
-esbuild is the only bundler, and a `webpack(config)` function in `next.config.js` is not executed (pnext warns once at config load when one is present). `turbopack.rules` loader chains, `turbopack.resolveAlias`, `transpilePackages`, `modularizeImports`, and `optimizePackageImports` are re-implemented on esbuild directly.
+A `webpack()` function that references `@svgr/webpack`, by far the most common custom-loader use, is auto-detected. pnext then compiles `.svg` imports to inline Preact components, matching that loader's default output. Root SVG attributes are spread first, so props such as `className`, `width`, and `height` override them. Without that reference, `.svg` imports keep the normal static-asset URL behavior.
 
-If `webpack()` references `@svgr/webpack` — the overwhelmingly common custom-loader use — pnext auto-detects it and compiles `.svg` imports to inline Preact components (root SVG attributes spread first, so `className`/`width`/`height`/etc. props override them), matching `@svgr/webpack`'s default output. Without that reference, `.svg` imports keep the normal static-asset URL behavior.
+### Cache state is per process
 
-## Optional native dependencies
+`revalidatePath`, `revalidateTag`, `unstable_cache`, and `'use cache'` entries live in the server process by default, so a multi-instance deployment revalidates one instance. Configure `cacheHandler` in `next.config.js` for a shared store.
 
-All three ship as `optionalDependencies`, so a normal install has them — same as Next. The graceful paths below only matter when the optional install fails.
+### Optional native dependencies
+
+All three ship as `optionalDependencies`, so a normal install has them, the same as Next. These paths only matter when the optional install fails.
 
 - `next/image`'s `/_next/image` optimizer needs `sharp`. The component, `images` config validation, and static imports work without it.
 - `next/og`'s `ImageResponse` needs `satori` and `@resvg/resvg-js`. Without them, or without a usable font, it answers with a valid placeholder PNG instead of failing the request.
 - `next/font/google` resolves the catalog through `next-font`. If it cannot, the build fails rather than falling back to a hosted font.
 
-## Smaller surfaces
+### Smaller surfaces
 
-- `userAgent()` uses an in-house parser covering mainstream browsers, engines, CPUs, and devices — not the full ua-parser-js database.
-- Only these `next/dist/*` paths are shimmed; any other deep import fails with an error naming this list.
+- `userAgent()` uses an in-house parser covering mainstream browsers, engines, CPUs, and devices, not the full ua-parser-js database.
+- React's taint functions do not exist under Preact, so pnext does not export them. What it implements is the guarantee `experimental.taint` exists for: with the flag on, `process.env` is registered as tainted, and passing that object as a client-component prop at any depth throws. Development shows the message in the nearest error boundary and production shows React's redacted error text, matching Next. Tainting your own objects or values is not available.
+- `ViewTransition` and `addTransitionType` are exported from the `react` entry so pages importing them render instead of throwing, and `next/link` accepts `transitionTypes`. Support stops there: the component is a passthrough that renders no DOM, and pnext does not drive `document.startViewTransition`, so declared names and types are recorded but no browser transition is played.
+- Only these `next/dist/*` paths are shimmed. Any other deep import fails with an error naming this list.
   - `next/dist/client/components/app-router-headers`
   - `next/dist/server/web/spec-extension/unstable-cache`
   - `next/dist/server/web/spec-extension/unstable-no-store`
   - `next/dist/server/web/spec-extension/revalidate`
   - `next/dist/server/app-render/work-unit-async-storage.external` (server only)
 
-## Cache state is per process
+## Feature notes
+
+The rest of the surface ships as well. Each note says where support stops short.
+
+### redirects and rewrites
+
+`redirects()` and `rewrites()` in `next.config.js` are both honored. Sources support the `:param`, `:param*`, `:param+`, `:param?`, and `:param(regex)` tokens, plus `has` and `missing` conditions on host, header, query, and cookie. Named capture groups feed their values into destination parameters.
+
+Rewrites accept the array form and the object form with `beforeFiles`, `afterFiles`, and `fallback`, and entries setting `basePath: false` match the raw path. An external `http` or `https` destination is proxied through a server-side fetch. After a rewrite fires, `usePathname()` and `useSearchParams()` still report the URL the browser asked for.
+
+Redirects use 308 for `permanent: true`, 307 for `permanent: false`, or an explicit `statusCode`, and they keep external destinations as redirects.
+
+One partial: fallback rewrites apply only to requests that would otherwise 404, and in development that check consults the route table alone, since there is no built output to look at.
+
+### after()
+
+`after()` from `next/server` runs work once the response is fully sent. Each callback runs exactly once, when the response closes, on every path: stream end, a redirect, a not-found, a thrown error, or a client abort. Calls nested inside an `after()` task run too. When the host platform supplies the Vercel request context, each task is also handed to its `waitUntil` so a serverless invocation stays alive until the task settles. An `after()` task that throws during a build prerender fails the build rather than quietly degrading the route.
+
+### next/form
+
+`Form` renders a GET form and intercepts submission into a client-side navigation, building the destination URL from the form's fields. String actions get the basePath applied and are prefetched like a link, including a re-prefetch when a revalidation invalidates them. Function actions pass straight through as React form actions with no interception. A submitter that overrides the encoding, method, or target falls back to the browser's native submit, and file inputs are not submitted with a string action. Both cases warn in development.
+
+### instrumentation and instrumentation-client
+
+An `instrumentation` file at the project root or in `src/` is bundled and imported once at server start. Its `register()` is awaited before the first request is served, and its `onRequestError` export is wired into the error funnel. When the app contains any edge entity, meaning a proxy or middleware, or a route declaring an edge runtime, a second freshly loaded instance is registered with `NEXT_RUNTIME` set to `edge`, mirroring Next's separate edge boot.
+
+An `instrumentation-client` file is bundled with any `instrumentationClientInject` entries ahead of it, in configured order, and loaded from the document head so it runs before hydration. Each module's `onRouterTransitionStart` export is called at the start of every soft navigation. Apps without such a file get no extra bundle and no extra head tag.
+
+### OpenTelemetry
+
+pnext emits Next's span taxonomy through the global `@opentelemetry/api` that your instrumentation file registers: a root request span carrying `next.route` and `http.status_code`, plus child spans for rendering, route handlers, `fetch`, middleware and proxy, and Pages Router data and API handlers. Incoming `traceparent` headers are extracted, and errors caught by the request funnel mark the root span.
+
+`@opentelemetry/api` is an optional dependency resolved from your own `node_modules`, so pnext and your SDK share one API singleton. When the package is absent, every tracing helper is inert. Keys listed in `experimental.clientTraceMetadata` are injected into the document head as meta tags.
+
+### MDX
+
+`.mdx` and `.md` modules compile through `@mdx-js/mdx`, an optional dependency loaded on the first MDX compile, so an app that never imports MDX does not need it installed. `createMDX()` from `@next/mdx` is understood at config load, so the remark, rehype, and recma plugins you configure there run. MDX files become routes only when `pageExtensions` lists the extension, matching Next. An `mdx-components` file supplies the component provider, and without one MDX emits plain host elements. One caveat: MDX currently compiles in the client graph, so treat an MDX module as client code.
+
+### Edge runtime
+
+A route or proxy declaring an edge runtime, and a Pages Router handler configured for `edge` or `experimental-edge`, runs with `process.env.NEXT_RUNTIME` set to `edge`, the `EdgeRuntime` global defined, and a `process` object that hides `version` and `versions` so code branching on those detects the edge environment. This is an emulation inside the same Bun process rather than a separate isolate, so the Edge API subset is not enforced: Node built-ins stay reachable, and code that only works because of that will still fail on a real edge platform.
+
+### Root params
+
+`next/root-params` resolves parameters from the root dynamic segment. It works in layouts, pages, and `'use cache'` functions, and inside `generateStaticParams` when a parent `generateStaticParams` already provided the parameter. Calling it inside a server action, inside `unstable_cache`, or from a route handler throws with the same diagnostics Next produces. Reading one marks every segment of the response as varying.
+
+### output: 'export' and output: 'standalone'
+
+`output: 'export'` writes a static tree to `out/`, or to `distDir` when the app configures a custom one. The tree carries the HTML and the flat per-page artifacts the client router fetches when no pnext server is present, the client runtime under `_next/static/chunks/`, the build manifests, the `public/` tree, and the not-found page. Dynamic routes without `generateStaticParams`, pages forcing dynamic rendering, and route handlers with disallowed segment config are build errors, as they are in Next.
 
-`revalidatePath`/`revalidateTag`, `unstable_cache`, and `'use cache'` entries live in the server process by default, so a multi-instance deployment revalidates one instance. Configure `cacheHandler` in `next.config.js` for a shared store.
+`output: 'standalone'` writes `.next/standalone/` with a `server.js` that boots on `PORT` and `HOSTNAME`, along with a `.nft.json` trace beside each page entry and a middleware manifest. Because pnext's production server runs under Bun, that launcher is a thin Node script that re-executes the real pnext server pointed back at the original build directory. The folder is therefore not a self-contained bundle you can ship on its own, because the build tree has to travel with it.

package/reference/config.md

@@ -1,9 +1,9 @@
 # Config
 
-pnext reads `pnext.config.ts` from the project root passed to the CLI. The file is optional.
+An optional `pnext.config.ts` in the project root, meaning the directory passed to the CLI.
 
 ```ts
-import type { pnextConfig } from '@wular/pnext';
+import type { PNextConfig } from '@wular/pnext'
 
 export default {
   outDir: '.pnext',
@@ -12,109 +12,56 @@ export default {
   compat: {
     next: true,
   },
-} satisfies pnextConfig;
+} satisfies PNextConfig
 ```
 
-With `compat.next`, `next.config.js` is loaded too, and it wins on the options both files can set (`basePath`, `assetPrefix`, `outDir`, `trailingSlash`, `skipTrailingSlashRedirect`, `productionBrowserSourceMaps`).
+This is the form `pnext create` scaffolds. With `compat.next`, pnext also loads `next.config.js`, and that file wins for the options both can set: `basePath`, `assetPrefix`, `outDir`, `trailingSlash`, `skipTrailingSlashRedirect`, and `productionBrowserSourceMaps`.
 
 ## Fields
 
-### `outDir`
+| Field                         | Default     | What it does                                                                                               |
+| ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `outDir`                      | `'.pnext'`  | Build output for HTML, client assets, cache files, and `manifest.json`.                                    |
+| `basePath`                    | `''`        | Path prefix for an app served below the domain root.                                                       |
+| `assetPrefix`                 | `basePath`  | URL prefix for emitted assets. Set it when assets come from a CDN.                                         |
+| `trailingSlash`               | `false`     | Canonicalizes URLs to a trailing slash and redirects the form without one.                                 |
+| `skipTrailingSlashRedirect`   | `false`     | Serves both slash forms with no canonical redirect, preserving authored hrefs.                             |
+| `productionBrowserSourceMaps` | `false`     | Emits external `.js.map` files next to production client chunks.                                           |
+| `prefetch`                    | `'visible'` | Default prefetch mode for links that set none of their own. See [Navigation](./navigation.md#prefetching). |
+| `workspaceRoot`               | inferred    | Monorepo root for resolving and reloading local workspace package imports.                                 |
+| `htmlLimitedBots`             | see below   | User agents that get blocking metadata in the head. Applies with `compat.next`.                            |
+| `adapter`                     | unset       | Narrows what a deployment adapter packs into its server function.                                          |
+| `compat`                      | all `false` | Turns on the React, Next, and React Compiler compatibility layers.                                         |
 
-Default: `'.pnext'`
+Worth knowing:
 
-Build output directory for HTML, client assets, cache files, and `manifest.json`.
+- Development client output is already unminified, so it never emits sourcemaps.
+- `workspaceRoot` is inferred from `package.json#workspaces` or `pnpm-workspace.yaml`, otherwise the app root. It does not change the app root used for `public/`, `.pnext/`, or `pnext.config.ts`. Set it only to override the inference.
+- The `htmlLimitedBots` default is a regex covering Twitterbot, Slackbot, Bingbot, Discordbot, LinkedInBot, and the Google and Lighthouse renderers. Matching user agents receive metadata blocked in the head instead of streamed into the body.
 
-### `basePath`
+## Compat modes
 
-Default: `''`
+| Flag                   | Effect                                                                     |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `compat.react`         | Aliases the React and React DOM entry points to Preact-backed shims.       |
+| `compat.next`          | Adds the `next/*` surface, `next.config.js`, and Next App Router behavior. |
+| `compat.reactCompiler` | Experimental React Compiler support for React-style Client Components.     |
 
-Path prefix for apps served below the domain root.
+Both `compat.next` and `compat.reactCompiler` imply `compat.react`. Direct Preact imports stay smaller than any of them, so reach for compat when you are running React-style components. React Compiler is not intended for components built around Preact Signals. See [Compatibility](./compat.md).
 
-### `assetPrefix`
+## Deployment adapter
 
-Default: `basePath`
+`exclude` and `keep` are string lists that adjust which directories and file suffixes an adapter packs. The Vercel adapter consumes them.
 
-URL prefix for emitted assets. Set it to serve `/assets/*` from a CDN.
-
-### `trailingSlash`
-
-Default: `false`
-
-Canonicalize URLs to a trailing slash, redirecting the unslashed form.
-
-### `skipTrailingSlashRedirect`
-
-Default: `false`
-
-Serve both the slashed and unslashed URL without a canonical redirect, and leave
-`<Link>` hrefs exactly as authored.
-
-### `productionBrowserSourceMaps`
-
-Default: `false`
-
-Emit external `.js.map` browser sourcemaps next to each production client chunk,
-linked by a `//# sourceMappingURL=` comment. Off by default (as in Next): maps
-publish your first-party source to every visitor and cost real build time.
-Development never emits them — dev client output is un-minified already.
-
-### `htmlLimitedBots`
-
-Default: a regex covering Twitterbot, Slackbot, Bingbot, Discordbot, LinkedInBot,
-and the Google/Lighthouse renderers.
-
-User agents matched by this pattern get metadata blocked in `<head>` rather than
-streamed into the body. `compat.next` only.
-
-### `adapter`
-
-Default: unset
-
-`exclude` and `keep` string lists overriding what a deployment adapter packs into
-the server function. Entries are directory names (`storybook-static`) or file
-suffixes (`.map`).
-
-### `workspaceRoot`
-
-Default: inferred from `package.json#workspaces` or `pnpm-workspace.yaml`, otherwise the app root.
-
-Monorepo root used to resolve and reload local workspace package imports. This does not change where pnext reads `public/`, writes `.pnext/`, or loads `pnext.config.ts`.
-
-### `compat.react`
-
-Default: `false`
-
-When `true`, pnext aliases `react`, `react-dom`, `react-dom/client`, `react-dom/server`, `react/jsx-runtime`, `react/jsx-dev-runtime`, and `react/compiler-runtime` onto Preact-backed shims.
-
-Use this when moving React-style components into a pnext app. Direct Preact imports are still smaller; `preact/compat` adds compatibility code only when your app imports React APIs.
-
-### `compat.next`
-
-Default: `false`
-
-Enables the `next/*` module surface, `next.config.js`, and the rest of the Next App Router behaviors for existing apps and shared packages. This implies `compat.react`.
-
-See [Compatibility](./compat.md).
-
-### `compat.reactCompiler`
-
-Default: `false`
-
-Experimental React Compiler support for React-style Client Components. This implies `compat.react`.
-
-Use this for components written with React hooks and props-heavy render paths where compiler memoization can reduce rerenders. Direct Preact code still gives the smallest bundles, and React Compiler compat is not recommended for components built around Preact Signals.
-
-## File Conventions
-
-Routes are loaded from `app/` or `src/app/`. If both exist, `app/` wins. Under
-`compat.next`, a `pages/` directory is materialized onto App Router routes; a
-hybrid app keeps its native `app/` routes.
-
-Static assets are loaded from `public/` at the project root.
-
-## Workspace Root
+```ts
+export default {
+  adapter: {
+    exclude: ['storybook-static', '.map'],
+    keep: ['runtime-assets', '.wasm'],
+  },
+} satisfies PNextConfig
+```
 
-pnext keeps the CLI root as the app root for `public/`, `.pnext/`, and `pnext.config.ts`.
+## Where pnext looks for files
 
-For monorepos, pnext also infers a workspace root by walking upward to `package.json#workspaces` or `pnpm-workspace.yaml`. Set `workspaceRoot` only when that inference should be overridden.
+Routes come from `app/` or `src/app/`, and `app/` wins if both exist. Static assets come from `public/` at the project root. Under `compat.next`, a `pages/` directory is materialized onto App Router routes, and a hybrid app keeps its native `app/` routes.