@wular/pnext 0.0.1

package/README.md

@@ -0,0 +1,153 @@
+<div align="center">
+
+# pnext
+
+**A fast little framework for server-first React apps, fully compatible with Next.js.**
+
+</div>
+
+## Measured against Next.js
+
+The same fixture source runs under both frameworks; `bun bench` measures them side by side and rewrites [`reference/performance.md`](./reference/performance.md) with your machine's absolute numbers. The ranges below span the fixtures — hello-world, an SSR site, and a mid-size admin dashboard (30 routes, 18 client islands):
+
+| | pnext vs Next.js |
+|---|--:|
+| Dev server ready | **2.5–3× faster** |
+| First page, cold | **6.5–13× faster** |
+| Warm request | **4–7.5× faster** |
+| HMR save → visible | **1–2.5× faster** |
+| Production build | **4.5–10× faster** |
+| First-page client JS (gzip) | **6–65× less** |
+
+Nothing is prebundled — the dev server compiles what a request needs and caches it content-addressed, so it's ready in ~100 ms at any app size.
+
+Core pnext (no Next compat) is its own story, and it's smaller still:
+
+- **Server-only pages ship 0 KB of JavaScript.**
+- A server-rendered page with links ships **~1 KB gzip** of framework, total; the router + prefetch runtime alone is **348 bytes**.
+- A fully hydrated route pays **~7.5 KB gzip** of framework — **12.5 KB** with React compat, **15 KB** with the full `next/*` surface. Next.js ships 130+ KB before your first component.
+
+Compatibility is proven, not promised: pnext runs Next.js's own test suite — 4,400+ tracked assertions passing — so `next/link`, `next/navigation`, `next/headers`, metadata, middleware, and friends behave the way you already know.
+
+## How
+
+One pipeline, three fast tools: [Bun](https://bun.sh) as runtime, esbuild as the only bundler (dev and prod are the same artifacts — no dev/prod drift), and oxc for parsing, resolving, and transforms. Preact renders and hydrates; React APIs work through compat. The dev server compiles exactly what a request needs, when it needs it.
+
+## Install
+
+```sh
+bun add -d @wular/pnext
+```
+
+```json
+{
+  "scripts": {
+    "dev": "pnext dev --port 3000",
+    "build": "pnext build",
+    "build:vercel": "pnext build --adapter vercel",
+    "start": "pnext start --port 3000",
+    "analyze": "pnext analyze"
+  }
+}
+```
+
+## App shape
+
+pnext looks for `app/` or `src/app/`:
+
+```txt
+src/app/
+  globals.css
+  page.tsx
+  layout.tsx
+  users/
+    [id]/
+      page.tsx
+  api/
+    hello/
+      route.ts
+public/
+  logo.svg
+```
+
+`public/` is served from `/`. Global CSS imported from the root layout is compiled and linked in the head, with your PostCSS/Tailwind setup. CSS from pages and components becomes route CSS; `.module.css` is scoped. `layout.tsx` can export `metadata`, a default wrapper component, or both — a metadata-only root layout lets pnext create the document shell.
+
+## Pages
+
+Pages and layouts are Server Components by default:
+
+```tsx
+export const metadata = {
+  title: 'My app',
+};
+
+export default async function Page() {
+  const post = await getPost();
+  return <article>{post.title}</article>;
+}
+```
+
+Add a Client Component only where the browser matters:
+
+```tsx
+'use client';
+
+import { useState } from 'preact/hooks';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+Server Components render Client Components with serializable props; Client Components server-render and hydrate. Server-rendered children passed into a Client Component stay on the server and ship no code.
+
+Dedupe repeated reads with server-only `cache()`:
+
+```tsx
+import { cache } from '@wular/pnext/cache';
+
+export const getPost = cache(async (id: string) => {
+  return db.post.findUnique({ where: { id } });
+});
+```
+
+## Routes
+
+`route.ts` files are HTTP handlers:
+
+```tsx
+import type { NextRequest } from '@wular/pnext/server';
+
+export function GET(request: NextRequest) {
+  const name = request.nextUrl.searchParams.get('name');
+  return Response.json({ hello: name ?? 'world' });
+}
+```
+
+Static `GET` handlers and `[param]` pages with a `params()` export are written as static files at build time; everything else stays runtime. `pnext build --adapter vercel` emits `.vercel/output` directly.
+
+## Types
+
+`pnext dev`, `build`, and `typegen` generate route types in `.pnext/types`; import typed route props from `#gen/app/...`.
+
+## Benchmarks
+
+```sh
+bun bench
+```
+
+Runs pnext and Next.js side by side on the shared fixtures in [`bench/`](./bench/) — dev cold start, warm requests, HMR, production build, shipped bytes — and rewrites [`reference/performance.md`](./reference/performance.md) with your machine's numbers. Don't take our word for it.
+
+## Reference
+
+- [Overview](./reference/overview.md)
+- [Routing](./reference/routing.md)
+- [Metadata](./reference/metadata.md)
+- [Rendering](./reference/rendering.md)
+- [CSS](./reference/css.md)
+- [Environment Variables](./reference/env.md)
+- [Compatibility](./reference/compat.md)
+- [Typegen](./reference/typegen.md)
+- [Config](./reference/config.md)
+- [Performance](./reference/performance.md)

package/bin/pnext

@@ -0,0 +1,67 @@
+#!/bin/sh
+
+script=$0
+
+# `dirname` is an external binary and `$(...)` forks a subshell, so spelling this
+# the obvious way costs two process creations on every command. Parameter
+# expansion plus a `cd` in *this* shell gets the same answer with no forks; the
+# cwd is restored before exec so relative arguments still resolve.
+resolve_dir() {
+  case $1 in
+    */*) dirpart=${1%/*} ;;
+    *) dirpart=. ;;
+  esac
+  opwd=$PWD
+  CDPATH= cd -P "$dirpart" 2>/dev/null || return 1
+  dir=$PWD
+  CDPATH= cd "$opwd" 2>/dev/null || return 1
+}
+
+while [ -L "$script" ]; do
+  resolve_dir "$script" || break
+  target=$(readlink "$script")
+  case "$target" in
+    /*) script=$target ;;
+    *) script=$dir/$target ;;
+  esac
+done
+
+resolve_dir "$script"
+
+# Bun decides its JSX transform (jsx vs. the dev-only jsxDEV, which calls
+# preact/jsx-dev-runtime with a different call signature) once per process,
+# from NODE_ENV at startup — not per file. Setting it later from inside
+# index.ts is too late: by the time that line runs, the entry file and
+# everything reached by its static imports have already been transpiled
+# with whatever NODE_ENV was inherited from the shell. So it must be
+# exported here, before exec, not in TS.
+if [ -z "$NODE_ENV" ]; then
+  case "$1" in
+    dev) export NODE_ENV=development ;;
+    *) export NODE_ENV=production ;;
+  esac
+fi
+
+# Exec through a bun binary literally named for the command ("pnext-dev",
+# "pnext-build", ...) so Activity Monitor and `ps` label every pnext process
+# 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
+# `-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
+# plain bun and the CLI creates the link for the next run.
+case "$1" in
+  dev|build|start|analyze|typegen) named=pnext-$1 ;;
+  *) named=pnext ;;
+esac
+
+bun_bin=$(command -v bun)
+for candidate in "${XDG_CACHE_HOME:-$HOME/.cache}"/pnext/bin/bun-*/"$named"; do
+  if [ -x "$candidate" ] && [ "$candidate" -ef "$bun_bin" ]; then
+    exec "$candidate" --conditions=react-server "$dir/../src/cli/index.ts" "$@"
+  fi
+done
+
+exec bun --conditions=react-server "$dir/../src/cli/index.ts" "$@"

package/config/lint/base.js

@@ -0,0 +1,48 @@
+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';
+
+export default tseslint.config(
+  includeIgnoreFile(path.join(import.meta.dirname, '../../.gitignore')),
+  { ignores: ['**/*.config.*', '**/*.d.ts', '**/.pnext/**', '**/dist/**'] },
+  {
+    files: ['**/*.js', '**/*.ts', '**/*.tsx'],
+    plugins: {
+      import: importPlugin,
+      turbo: turboPlugin,
+    },
+    extends: [
+      eslint.configs.recommended,
+      ...tseslint.configs.recommended,
+      ...tseslint.configs.recommendedTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    rules: {
+      // @ts-ignore
+      ...turboPlugin.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/consistent-type-imports': [
+        'warn',
+        { prefer: 'type-imports', fixStyle: 'inline-type-imports', disallowTypeAnnotations: false },
+      ],
+      'prefer-const': 'off',
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/prefer-nullish-coalescing': 'off',
+      '@typescript-eslint/prefer-regexp-exec': 'off',
+    },
+  },
+  {
+    linterOptions: { reportUnusedDisableDirectives: true },
+    languageOptions: { parserOptions: { projectService: true } },
+  },
+);

package/config/ts/base.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Default",
+  "compilerOptions": {
+    "declaration": false,
+    "esModuleInterop": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": [
+      "ESNext"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "target": "ES2021",
+    "checkJs": true,
+    "allowJs": true,
+    "noEmit": true
+  }
+}

package/config/ts/react.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React Library",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ESNext"
+    ],
+    "jsx": "react-jsx"
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@wular/pnext",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "pnext": "bin/pnext"
+  },
+  "files": [
+    "bin",
+    "config",
+    "src",
+    "tsconfig.json",
+    "reference"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./internal": "./src/internal.ts",
+    "./cache": "./src/api/cache.ts",
+    "./dynamic": "./src/api/dynamic.tsx",
+    "./link": "./src/api/link.tsx",
+    "./navigation": "./src/api/navigation.ts",
+    "./navigation/client": "./src/api/client-navigation.ts",
+    "./server": "./src/api/server.ts"
+  },
+  "scripts": {
+    "lint": "bun scripts/check-compat-boundary.ts && eslint . --max-warnings 0 && tsc --noEmit",
+    "bench": "bun bench/run.ts",
+    "clean": "rm -rf .turbo .pnext node_modules",
+    "prepublishOnly": "bun run lint",
+    "version-bump:patch": "bun scripts/bump.mjs patch",
+    "version-bump:minor": "bun scripts/bump.mjs minor",
+    "version-bump:major": "bun scripts/bump.mjs major"
+  },
+  "dependencies": {
+    "client-only": "^0.0.1",
+    "dotenv": "^16.0.3",
+    "esbuild": "^0.25.12",
+    "oxc-parser": "0.142.0",
+    "oxc-resolver": "^11.24.2",
+    "oxc-transform": "0.136.0",
+    "preact": "^10.29.2",
+    "preact-render-to-string": "^6.7.0",
+    "react-compiler-runtime": "^1.0.0",
+    "server-only": "^0.0.1",
+    "web-vitals": "^4.2.4"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1.4.0",
+    "@eslint/js": "^9.38.0",
+    "@types/bun": "^1.3.0",
+    "eslint": "^9.38.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-turbo": "^2.5.8",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2"
+  },
+  "optionalDependencies": {
+    "@mdx-js/mdx": "^3.1.0",
+    "@opentelemetry/api": "^1.7.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+    "next-font": "^2.0.2",
+    "sass": "^1.80.0",
+    "satori": "^0.12.0",
+    "sharp": "^0.34.0"
+  }
+}

package/reference/compat.md

@@ -0,0 +1,63 @@
+# 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.
+
+```ts
+export default {
+  compat: {
+    react: true, // map react/react-dom onto Preact
+    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.
+
+Importing `next/*` or `react` without the matching compat mode is a build error naming the flag to enable.
+
+Everything below is a place pnext deliberately does not match Next. It is the whole list.
+
+## Preact, not React
+
+`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.
+
+Direct Preact imports and Preact Signals need no compat and produce smaller bundles than `preact/compat`.
+
+## 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.
+
+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
+
+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
+
+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.
+
+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.
+
+## Optional native dependencies
+
+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.
+
+- `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
+
+- `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.
+  - `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
+
+`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.

package/reference/config.md

@@ -0,0 +1,120 @@
+# Config
+
+pnext reads `pnext.config.ts` from the project root passed to the CLI. The file is optional.
+
+```ts
+import type { pnextConfig } from '@wular/pnext';
+
+export default {
+  outDir: '.pnext',
+  basePath: '',
+  productionBrowserSourceMaps: false,
+  compat: {
+    next: true,
+  },
+} 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`).
+
+## Fields
+
+### `outDir`
+
+Default: `'.pnext'`
+
+Build output directory for HTML, client assets, cache files, and `manifest.json`.
+
+### `basePath`
+
+Default: `''`
+
+Path prefix for apps served below the domain root.
+
+### `assetPrefix`
+
+Default: `basePath`
+
+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
+
+pnext keeps the CLI root as the app root for `public/`, `.pnext/`, and `pnext.config.ts`.
+
+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.

package/reference/css.md

@@ -0,0 +1,58 @@
+# 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 CSS can use local workspace package imports, font files, image assets, and the app's PostCSS/Tailwind setup.
+
+## PostCSS
+
+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.
+
+```tsx
+import type { ComponentChildren } from 'preact';
+import './globals.css';
+
+export default function Layout({ children }: { children: ComponentChildren }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Route CSS
+
+Import plain CSS from pages, layouts, or components:
+
+```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.
+
+## CSS Modules
+
+Use `.module.css` for scoped classes:
+
+```css
+.title {
+  color: rebeccapurple;
+}
+```
+
+```tsx
+import styles from './page.module.css';
+
+export default function Page() {
+  return <h1 className={styles.title}>Hello</h1>;
+}
+```
+
+CSS module class names are scoped in the emitted CSS and match the server-rendered HTML.