@wular/pnext 0.0.6 → 0.0.8

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
 
@@ -63,7 +67,9 @@ 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>
+  return (
+    <button onClick={() => setCount(count + 1)}>Count {count}</button>
+  )
 }
 ```
 
@@ -98,14 +104,14 @@ export async function GET(request: NextRequest) {
 
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {

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 {
@@ -12,52 +12,117 @@ export default {
 }
 ```
 
-`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.

package/reference/css.md

@@ -1,55 +1,31 @@
 # CSS
 
-## Global CSS
-
-Import global styles from the root layout. pnext compiles global CSS once and links it from every page as `/assets/global.css`.
+Global styles, per-route styles, CSS Modules, and the compat-only preprocessors.
 
-Global CSS can use local workspace package imports, font files, image assets, and the app's PostCSS/Tailwind setup.
-
-## PostCSS
+## Global CSS
 
-When the app root has a `postcss.config.{cjs,js,mjs}`, pnext runs its plugins on every emitted stylesheet, in a worker thread. Tailwind v4 (`@tailwindcss/postcss`) stays warm there, so dev rebuilds are incremental; config-file edits need a dev-server restart.
+Imported from the root layout. pnext compiles it once and links it from every page as `/assets/global.css`.
 
 ```tsx
-import type { ComponentChildren } from 'preact'
+// app/layout.tsx
 import './globals.css'
-
-export default function Layout({
-  children,
-}: {
-  children: ComponentChildren
-}) {
-  return (
-    <html>
-      <body>{children}</body>
-    </html>
-  )
-}
 ```
 
-## Route CSS
+Global CSS can import local workspace packages, font files, image assets, and the app's PostCSS or Tailwind setup.
+
+## Route and component CSS
 
-Import plain CSS from pages, layouts, or components:
+Any page, layout, or component can import a stylesheet.
 
 ```tsx
 import './page.css'
-
-export default function Page() {
-  return <h1 className="title">Hello</h1>
-}
 ```
 
-pnext emits route CSS only for routes that import CSS. A route with CSS imports gets a linked `/assets/<route>.css` chunk.
+pnext emits CSS only for routes that import it. A route stylesheet is named from the route id, as `/assets/<route-id>.css`. When a compat build splits one into chunks, each name gains an index suffix.
 
 ## CSS Modules
 
-Use `.module.css` for scoped classes:
-
-```css
-.title {
-  color: rebeccapurple;
-}
-```
+A `.module.css` file gives scoped class names that match the server-rendered HTML.
 
 ```tsx
 import styles from './page.module.css'
@@ -59,4 +35,33 @@ export default function Page() {
 }
 ```
 
-CSS module class names are scoped in the emitted CSS and match the server-rendered HTML.
+Under `compat.next`, a `:global(...)` wrapper leaves the enclosed selector unscoped.
+
+## Tailwind and PostCSS
+
+A `postcss.config.{cjs,js,mjs}` file at the app root makes pnext run its plugins on every emitted stylesheet. Tailwind v4 stays warm in development. Editing the config file requires a dev-server restart.
+
+## Sass
+
+Requires `compat.next` and the optional `sass` dependency. `.scss`, `.sass`, `.module.scss`, and `.module.sass` imports compile, and `sassOptions.includePaths` from `next.config.js` is honored. If `sass` is unavailable, Sass imports produce no CSS rather than breaking a non-Sass app.
+
+## styled-jsx
+
+Requires `compat.next`. Style blocks and `styled-jsx/css` are transformed to pnext's own runtime, which collects server styles and mirrors client styles into the document head. Apps do not need to install `styled-jsx`.
+
+## Lightning CSS
+
+Requires `compat.next` and the app's own `lightningcss` package.
+
+- `experimental.useLightningcss` transforms CSS with it.
+- `experimental.lightningCssFeatures` controls which features are included or excluded.
+
+CSS passes through untransformed when the package is absent or the transform fails.
+
+## Nonces and inline CSS
+
+pnext reads a CSP nonce from the request `Content-Security-Policy` header and applies it to generated styles. With `experimental.inlineCss`, production documents inline route and global CSS in nonce-bearing style tags, while development keeps stylesheet links.
+
+## Chunking and order
+
+`experimental.cssChunking` groups compatible route stylesheets into fewer files while preserving each route's stylesheet order. It splits them instead when sharing a chunk would change cascade order or make a chunk too large.

package/reference/dev.md

@@ -1,20 +1,18 @@
-# Dev Server
+# Development
 
-`pnext dev` starts a Bun HTTP server for local development.
+The `pnext` CLI carries the whole flow: `dev` while you build, `analyze` to inspect what ships, `build` and `start` for production.
 
-## CLI
-
-```txt
+```sh
 pnext dev [directory] [--port 3000] [--hostname 127.0.0.1]
 pnext build [directory] [--adapter vercel] [--verbose]
 pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
 pnext analyze [route] [directory] [--brotli] [--files] [--json]
 pnext typegen [directory]
+pnext create <directory> [--no-install]
+pnext migrate [directory] [--dry-run]
 ```
 
-`analyze` takes a route (`/users/[id]` or a concrete path like `/users/ada`) to report on that route only.
-
-Add `@wular/pnext` as a package dependency and put `pnext` in package scripts:
+`create` scaffolds a new app with everything set up. `migrate` converts a Next.js project in place: it rewrites `package.json` and `tsconfig.json` and creates a `pnext.config.ts` with `compat.next` enabled, without editing app source; `--dry-run` previews. To set a project up by hand, add the package and scripts:
 
 ```json
 {
@@ -30,40 +28,35 @@ Add `@wular/pnext` as a package dependency and put `pnext` in package scripts:
 }
 ```
 
-The package exposes a `pnext` binary. Package managers make it available inside script `PATH`.
+## Dev server
 
-## Processes
+`pnext dev` starts a Bun HTTP server that scans the route tree, renders matching pages on request, and serves static assets from `public/`. Client route entries are built on demand and cached in `.pnext/cache`. Browser pages reload on route-tree changes over a server-sent events stream at `/__pnext/events`; the other `/__pnext/*` endpoints are implementation details, not application routes.
 
-pnext processes are labelled in Activity Monitor and `ps`: `pnext dev` shows
-up as a single `pnext-dev` server process, `pnext build` as `pnext-build`, and
-esbuild's service process as `pnext-esbuild`. Tailwind and PostCSS run in a
-worker thread inside the server process, not as child processes.
+The dev server does not typecheck in the request path; run your package's lint and typecheck scripts separately. `pnext typegen` regenerates the route types on demand; see [Type Safety](./typegen.md).
 
-The dev server re-execs itself — same pid — when its memory passes
-`PNEXT_DEV_MAX_RSS_MB` (default 2048). The esbuild service is stopped and
-respawned past `PNEXT_DEV_MAX_ESBUILD_RSS_MB` (default 1024).
+In Activity Monitor and `ps`, the dev server runs as `pnext-dev`, builds as `pnext-build`, and the bundler service as `pnext-esbuild`. The dev server re-execs itself when its memory passes `PNEXT_DEV_MAX_RSS_MB` (default 2048), and restarts the bundler past `PNEXT_DEV_MAX_ESBUILD_RSS_MB` (default 1024).
 
-## Responsibilities
+## Analyze
 
-- Scan the route tree.
-- Render matching pages on request.
-- Serve static assets from `public/`.
-- Build client route entries on demand with esbuild.
-- Cache generated client entries in `.pnext/cache`.
-- Notify the browser of route-tree changes through `/__pnext/events`.
+`pnext analyze` reports the client JavaScript behind each route. Optionally pass a route, either a template like `/users/[id]` or a concrete path, to report on that route only. `--files` breaks the report into files, `--brotli` measures with brotli instead of gzip, and `--json` emits machine-readable output.
 
-## Cache
+## Build and run
 
-Client entry cache keys include the route id and source content hash. Cached entries are stored below `.pnext/cache/client`.
+`pnext build` makes the production build and `pnext start` serves it. Routes render on the server per request; ones that never read the request are prerendered to static HTML at build time. A `compat.next` build typechecks off-thread alongside bundling.
 
-## Reload Events
+Debug flags: `--experimental-build-mode compile|generate` splits the build into its two phases, `--debug-build-paths <paths>` narrows diagnostics to matching paths, and `--debug-prerender` prints prerender diagnostics.
 
-The dev server exposes a server-sent events stream at `/__pnext/events`. Browser pages reload when app files change.
+## Deploy
 
-## Typechecking
+pnext deploys anywhere Bun runs: a VPS, a container, or any host you control. Run `pnext build` on the machine or in CI, then `pnext start` serves the app on your port.
 
-The dev server does not typecheck in the request path. Run package lint or typecheck commands separately. `pnext build` under `compat.next` typechecks off-thread, in parallel with bundling, and reports it on its own line.
+Vercel has a dedicated adapter: `pnext build --adapter vercel` writes Build Output to `.vercel/output`. Static pages and static route-handler responses are emitted as files; everything dynamic runs in a single `_pnext` function on Vercel's Bun runtime.
 
-## Server Adapter
+## Environment variables
 
-Use `pnext build --adapter vercel` to write Vercel Build Output at `.vercel/output`. Static pages and static `GET` route-handler outputs are emitted as files. Everything dynamic — pages, route handlers, and `proxy.ts` — is served by a single `_pnext` function on Vercel's Bun runtime; the proxy's `config.matcher` patterns become routes into it.
+- `PNEXT_COMPAT=next`: Next compatibility without a config file. See [Compatibility](./compat.md).
+- `PNEXT_TYPECHECK=classic`: in-process TypeScript checker instead of the native one.
+- `PNEXT_CLIENT_METAFILE=1`: write the client esbuild metafile to the output directory.
+- `PNEXT_CLIENT_PROFILE=1`: print client-build phase timings.
+- `PNEXT_DEV_PROFILE=1`: print dev request and build timings.
+- `PNEXT_BOOT_TRACE=1`: print boot-phase timings and memory readings.