npm - @wular/pnext - Versions diffs - 0.0.2 → 0.0.4 - Mend

@wular/pnext 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/README.md +76 -20
package/package.json +3 -2
package/reference/data/bench.json +513 -0
package/reference/performance.md +75 -48
package/src/api/router/runtime.ts +60 -21
package/src/cache/context.ts +4 -1
package/src/cli/build.ts +37 -5
package/src/cli/dev.ts +6 -0
package/src/cli/index.ts +17 -3
package/src/cli/request-pipeline.ts +1340 -0
package/src/cli/server-entry.ts +180 -0
package/src/cli/start.ts +39 -1311
package/src/client/build.ts +59 -20
package/src/client/chunk-fold.ts +40 -0
package/src/client/compat-surface.ts +175 -0
package/src/client/entry.ts +67 -52
package/src/compat/actions/action-client.ts +8 -1
package/src/compat/actions/action-dispatch.ts +11 -1
package/src/compat/actions/discovery.ts +23 -6
package/src/compat/bundler/optimize-package-imports.ts +5 -1
package/src/compat/bundler/worker.ts +2 -1
package/src/compat/client/errors/bare-boundary.ts +32 -0
package/src/compat/client/errors/error-boundary.ts +1 -15
package/src/compat/client/errors/primitive-throw.ts +16 -0
package/src/compat/client/link-status.ts +1 -1
package/src/compat/css/lightningcss.ts +2 -1
package/src/compat/css/modules.ts +4 -3
package/src/compat/lifecycle/instrumentation-client.ts +1 -1
package/src/compat/lifecycle/instrumentation.ts +5 -2
package/src/compat/next/config-loader.ts +33 -5
package/src/compat/next/dynamic.tsx +9 -5
package/src/compat/next/link-validation-transform.ts +5 -1
package/src/compat/next/link.tsx +51 -58
package/src/compat/pages/client-plugin.ts +2 -1
package/src/compat/react/action-state.ts +159 -0
package/src/compat/react/client-lite.ts +74 -0
package/src/compat/react/hooks-extra.ts +92 -0
package/src/compat/react/parity.ts +128 -0
package/src/compat/react/preact.ts +33 -420
package/src/compat/react/server-inserted-html.ts +14 -7
package/src/compat/react/use.ts +72 -0
package/src/compat/register/actions.ts +27 -7
package/src/compat/register/segment.ts +16 -6
package/src/config.ts +15 -1
package/src/css/build.ts +13 -2
package/src/dev/imports.ts +34 -5
package/src/dev/module-cache.ts +19 -0
package/src/dev/module-transform.ts +7 -1
package/src/dev/server.ts +91 -22
package/src/dynamic/source.ts +36 -27
package/src/ppr.ts +5 -4
package/src/proxy.ts +5 -1
package/src/render/island-context.ts +21 -3
package/src/render/renderer.ts +102 -26
package/src/resolve/engine.ts +12 -2
package/src/resolve/scan-facts.ts +239 -1
package/src/routing/href.ts +4 -5
package/src/routing/routes.ts +26 -41
package/src/runtime/server.ts +8 -4
package/src/runtime/vendor.ts +1 -1
package/src/typegen.ts +3 -3
package/src/utils/esbuild.ts +58 -0
package/src/utils/fs.ts +14 -2
package/src/utils/native-require.ts +28 -0

package/README.md CHANGED Viewed

@@ -2,12 +2,10 @@
 # pnext
-**A fast little framework for server-first React apps, fully compatible with Next.js.**
+**A fast little framework for server-first React apps, fully compatible with Next.js.**[<sup>1</sup>](./reference/compat.md)
 </div>
-Server-rendered pages ship **0 KB** of JavaScript — **~1 KB gzip** with client-side navigation and prefetching. Interactive pages hydrate on Preact for **~7.5 KB** of framework, or **~12.5 KB** with React compatibility. Everything is instant: the dev server starts **~3× faster** than Next's on **~4× less memory**, and production builds run **4.5–10× faster**. The Next.js App Router compatibility is validated against Next's own test suite, 4,400+ assertions passing.
 ## Getting started
 A new app:
@@ -16,7 +14,7 @@ A new app:
 bunx @wular/pnext create my-app
 ```
-Migrating a Next.js app — rewrites scripts and config in place, scans your source, and reports anything that needs a look (never edits your code):
+Migrating a Next.js app? This rewrites scripts and config in place, scans your source, and reports anything that needs a look (it never edits your code):
 ```sh
 bunx @wular/pnext migrate
@@ -24,27 +22,85 @@ bunx @wular/pnext migrate
 Or by hand: `bun add -d @wular/pnext`, then `pnext dev`.
-Adoption is incremental: core pnext is based on 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. See [Compatibility](./reference/compat.md).
+## 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).
+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).
+## A quick tour
+### Your first page
+Routes live in `app/`. A `page.tsx` is a Server Component by default. It runs only on the server, so it can be async and talk to your database, filesystem, or internal services directly. None of that code reaches the browser:
+```tsx
+// app/posts/[id]/page.tsx
+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 } });
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>{post.body}</p>
+    </article>
+  );
+}
+```
+This page ships **0 KB** of JavaScript. Layouts work the same way: the root `layout.tsx` owns `<html>` and `<body>` and can export `metadata`.
+### Adding interactivity
-## Measured against Next.js
+Mark a component with `"use client"` where you need state, effects, or event handlers. Server Components render it into the page, and only that island hydrates in the browser:
-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):
+```tsx
+// app/counter.tsx
+"use client";
+import { useState } from "preact/hooks";
-|                             |                   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** |
-| Dev server memory           |                    **3.5–4× less** |
-| Build peak memory           |                      **3–4× less** |
-| Framework install size      | **42× smaller** (6.7 MB vs 286 MB) |
-| First-page client JS (gzip) |                     **6–65× less** |
+export function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial);
+  return <button onClick={() => setCount(count + 1)}>Count {count}</button>;
+}
+```
+Client Components hydrate on Preact for ~7.5 KB of framework, or ~12.5 KB with [`compat.react`](./reference/compat.md) if you want to run React components and libraries unchanged. Offscreen islands can stay out of the initial bundle entirely with `dynamic({ load: 'visible' })`.
+### Streaming
+Wrap slow server work in `<Suspense>`. The shell streams immediately and the content follows when it's ready:
+```tsx
+import { Suspense } from "@wular/pnext";
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading comments…</p>}>
+      <Comments />
+    </Suspense>
+  );
+}
+```
+### APIs and everything else
+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());
+}
+```
-Nothing is prebundled — the dev server compiles what a request needs and caches it content-addressed, which is why readiness doesn't scale with app size. One metric goes the other way: the production server idles ~10 MB heavier than Next's (~113 vs ~101 MB, Bun's runtime baseline) while answering warm requests up to 2× faster.
+- `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.
-## Learn
+## 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:

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "bin": {
     "pnext": "bin/pnext"
@@ -23,7 +23,8 @@
     "./link": "./src/api/link.tsx",
     "./navigation": "./src/api/navigation.ts",
     "./navigation/client": "./src/api/client-navigation.ts",
-    "./server": "./src/api/server.ts"
+    "./server": "./src/api/server.ts",
+    "./config/*": "./config/*"
   },
   "scripts": {
     "lint": "bun scripts/check-compat-boundary.ts && eslint . --max-warnings 0 && tsc --noEmit",

package/reference/data/bench.json ADDED Viewed

@@ -0,0 +1,513 @@
+{
+  "run": {
+    "date": "2026-08-20",
+    "machine": "CI — Blacksmith 4 vCPU (Intel Xeon), 16 GB RAM, Ubuntu 22.04 x64",
+    "bun": "1.3.10",
+    "next": "16.2.12",
+    "runs": "5 per metric (first discarded), medians reported"
+  },
+  "fixtures": [
+    {
+      "id": "hello",
+      "label": "hello-world",
+      "blurb": "A single page."
+    },
+    {
+      "id": "ssr",
+      "label": "ssr",
+      "blurb": "A server-rendered site."
+    },
+    {
+      "id": "dashboard",
+      "label": "dashboard",
+      "blurb": "A mid-size admin app — 30 routes, 18 client islands."
+    }
+  ],
+  "metrics": [
+    {
+      "id": "dev-ready",
+      "label": "Dev server ready",
+      "category": "dev",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          56.4,
+          "56.4 ms",
+          212.3,
+          "212.3 ms",
+          3.76
+        ],
+        "ssr": [
+          56,
+          "56.0 ms",
+          212.8,
+          "212.8 ms",
+          3.8
+        ],
+        "dashboard": [
+          57.1,
+          "57.1 ms",
+          246.4,
+          "246.4 ms",
+          4.31
+        ]
+      }
+    },
+    {
+      "id": "dev-first-page",
+      "label": "Dev first page HTML",
+      "category": "dev",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          79.9,
+          "79.9 ms",
+          993.5,
+          "993.5 ms",
+          12.44
+        ],
+        "ssr": [
+          93.5,
+          "93.5 ms",
+          1043.3,
+          "1043.3 ms",
+          11.16
+        ],
+        "dashboard": [
+          127,
+          "127.0 ms",
+          1285.8,
+          "1285.8 ms",
+          10.12
+        ]
+      }
+    },
+    {
+      "id": "dev-warm",
+      "label": "Dev warm request (p50 of 7)",
+      "category": "dev",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          3,
+          "3.0 ms",
+          14,
+          "14.0 ms",
+          4.69
+        ],
+        "ssr": [
+          16.5,
+          "16.5 ms",
+          26.4,
+          "26.4 ms",
+          1.6
+        ],
+        "dashboard": [
+          21.6,
+          "21.6 ms",
+          34.1,
+          "34.1 ms",
+          1.58
+        ]
+      }
+    },
+    {
+      "id": "hmr",
+      "label": "HMR save → visible",
+      "category": "dev",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          21.9,
+          "21.9 ms",
+          44.8,
+          "44.8 ms",
+          2.04
+        ],
+        "ssr": [
+          264.3,
+          "264.3 ms",
+          68.3,
+          "68.3 ms",
+          0.26
+        ],
+        "dashboard": [
+          300.4,
+          "300.4 ms",
+          97.6,
+          "97.6 ms",
+          0.32
+        ]
+      }
+    },
+    {
+      "id": "build-wall",
+      "label": "Production build (wall)",
+      "category": "build",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          291.3,
+          "291.3 ms",
+          2569.4,
+          "2569.4 ms",
+          8.82
+        ],
+        "ssr": [
+          310.5,
+          "310.5 ms",
+          2738.8,
+          "2738.8 ms",
+          8.82
+        ],
+        "dashboard": [
+          637.5,
+          "637.5 ms",
+          4566.3,
+          "4566.3 ms",
+          7.16
+        ]
+      }
+    },
+    {
+      "id": "prod-start",
+      "label": "Prod start (ready)",
+      "category": "build",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          60.7,
+          "60.7 ms",
+          110.9,
+          "110.9 ms",
+          1.83
+        ],
+        "ssr": [
+          57.1,
+          "57.1 ms",
+          105.5,
+          "105.5 ms",
+          1.85
+        ],
+        "dashboard": [
+          55.6,
+          "55.6 ms",
+          128.8,
+          "128.8 ms",
+          2.32
+        ]
+      }
+    },
+    {
+      "id": "prod-warm",
+      "label": "Prod warm request (p50 of 7)",
+      "category": "build",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          0.6,
+          "0.6 ms",
+          1.2,
+          "1.2 ms",
+          2.05
+        ],
+        "ssr": [
+          0.5,
+          "0.5 ms",
+          1.3,
+          "1.3 ms",
+          2.5
+        ],
+        "dashboard": [
+          0.5,
+          "0.5 ms",
+          1.7,
+          "1.7 ms",
+          3.41
+        ]
+      }
+    },
+    {
+      "id": "dev-rss",
+      "label": "Dev server RSS (ready + 7 warm)",
+      "category": "memory",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          130.8,
+          "130.8 MB",
+          536.4,
+          "536.4 MB",
+          4.1
+        ],
+        "ssr": [
+          151.3,
+          "151.3 MB",
+          553.6,
+          "553.6 MB",
+          3.66
+        ],
+        "dashboard": [
+          168.6,
+          "168.6 MB",
+          577.1,
+          "577.1 MB",
+          3.42
+        ]
+      }
+    },
+    {
+      "id": "build-rss",
+      "label": "Prod build peak RSS",
+      "category": "memory",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          124.2,
+          "124.2 MB",
+          455.8,
+          "455.8 MB",
+          3.67
+        ],
+        "ssr": [
+          136.8,
+          "136.8 MB",
+          456.6,
+          "456.6 MB",
+          3.34
+        ],
+        "dashboard": [
+          188,
+          "188.0 MB",
+          569,
+          "569.0 MB",
+          3.03
+        ]
+      }
+    },
+    {
+      "id": "prod-rss",
+      "label": "Prod server RSS (ready + 7 warm)",
+      "category": "memory",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          85.2,
+          "85.2 MB",
+          85.7,
+          "85.7 MB",
+          1.01
+        ],
+        "ssr": [
+          86,
+          "86.0 MB",
+          85.9,
+          "85.9 MB",
+          1
+        ],
+        "dashboard": [
+          87.3,
+          "87.3 MB",
+          90.6,
+          "90.6 MB",
+          1.04
+        ]
+      }
+    },
+    {
+      "id": "install",
+      "label": "Framework install size",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ],
+        "ssr": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ],
+        "dashboard": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ]
+      }
+    },
+    {
+      "id": "js-gzip",
+      "label": "First-page client JS (gzip)",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          2.19,
+          "2.19 KB",
+          141.78,
+          "141.78 KB",
+          64.67
+        ],
+        "ssr": [
+          11.39,
+          "11.39 KB",
+          142.03,
+          "142.03 KB",
+          12.47
+        ],
+        "dashboard": [
+          15.26,
+          "15.26 KB",
+          144.85,
+          "144.85 KB",
+          9.5
+        ]
+      }
+    },
+    {
+      "id": "js-raw",
+      "label": "First-page client JS (raw)",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          4.43,
+          "4.43 KB",
+          502.47,
+          "502.47 KB",
+          113.36
+        ],
+        "ssr": [
+          27.36,
+          "27.36 KB",
+          502.78,
+          "502.78 KB",
+          18.37
+        ],
+        "dashboard": [
+          38.51,
+          "38.51 KB",
+          507.42,
+          "507.42 KB",
+          13.18
+        ]
+      }
+    },
+    {
+      "id": "js-files",
+      "label": "First-page JS files",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          3,
+          "3",
+          5,
+          "5",
+          1.67
+        ],
+        "ssr": [
+          4,
+          "4",
+          6,
+          "6",
+          1.5
+        ],
+        "dashboard": [
+          6,
+          "6",
+          9,
+          "9",
+          1.5
+        ]
+      }
+    },
+    {
+      "id": "zero-island",
+      "label": "Zero-island route client JS",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          4.43,
+          "4.43 KB",
+          502.47,
+          "502.47 KB",
+          113.36
+        ],
+        "ssr": [
+          4.46,
+          "4.46 KB",
+          502.47,
+          "502.47 KB",
+          112.56
+        ]
+      }
+    }
+  ],
+  "headlines": [
+    {
+      "label": "Dev server ready",
+      "direction": "faster",
+      "value": "3.8–4.3×"
+    },
+    {
+      "label": "First page, cold",
+      "direction": "faster",
+      "value": "10–12×"
+    },
+    {
+      "label": "Warm request (dev)",
+      "direction": "faster",
+      "value": "1.6–4.7×"
+    },
+    {
+      "label": "Production build",
+      "direction": "faster",
+      "value": "7.2–8.8×"
+    },
+    {
+      "label": "Warm request (prod)",
+      "direction": "faster",
+      "value": "2–3.4×"
+    },
+    {
+      "label": "Dev server memory",
+      "direction": "less",
+      "value": "3.4–4.1×"
+    },
+    {
+      "label": "First-page client JS (gzip)",
+      "direction": "less",
+      "value": "9.5–65×"
+    },
+    {
+      "label": "Framework install size",
+      "direction": "smaller",
+      "value": "59×",
+      "detail": "7.1 MB vs 420.7 MB"
+    }
+  ],
+  "clientRuntimes": [
+    {
+      "name": "router-prefetch-only",
+      "raw": "473 B",
+      "gzip": "348 B",
+      "brotli": "283 B"
+    },
+    {
+      "name": "combined-router-hydrator",
+      "raw": "10.47 KB",
+      "gzip": "4.47 KB",
+      "brotli": "4.07 KB"
+    }
+  ]
+}