@wular/pnext 0.0.1 → 0.0.3

package/README.md

@@ -2,152 +2,117 @@
 
 # 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>
 
-## Measured against Next.js
+## Getting started
 
-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
+A new app:
 
 ```sh
-bun add -d @wular/pnext
+bunx @wular/pnext create my-app
 ```
 
-```json
-{
-  "scripts": {
-    "dev": "pnext dev --port 3000",
-    "build": "pnext build",
-    "build:vercel": "pnext build --adapter vercel",
-    "start": "pnext start --port 3000",
-    "analyze": "pnext analyze"
-  }
-}
-```
+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):
 
-## 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
+```sh
+bunx @wular/pnext migrate
 ```
 
-`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
+Or by hand: `bun add -d @wular/pnext`, then `pnext dev`.
 
-Pages and layouts are Server Components by default:
+## Incremental by design
 
-```tsx
-export const metadata = {
-  title: 'My app',
-};
+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).
 
-export default async function Page() {
-  const post = await getPost();
-  return <article>{post.title}</article>;
-}
-```
+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).
 
-Add a Client Component only where the browser matters:
+## A quick tour
 
-```tsx
-'use client';
+### Your first page
 
-import { useState } from 'preact/hooks';
+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:
 
-export function Counter() {
-  const [count, setCount] = useState(0);
-  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+```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>
+  );
 }
 ```
 
-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.
+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
 
-Dedupe repeated reads with server-only `cache()`:
+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:
 
 ```tsx
-import { cache } from '@wular/pnext/cache';
+// app/counter.tsx
+"use client";
+import { useState } from "preact/hooks";
 
-export const getPost = cache(async (id: string) => {
-  return db.post.findUnique({ where: { id } });
-});
+export function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial);
+  return <button onClick={() => setCount(count + 1)}>Count {count}</button>;
+}
 ```
 
-## Routes
+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' })`.
 
-`route.ts` files are HTTP handlers:
+### Streaming
 
-```tsx
-import type { NextRequest } from '@wular/pnext/server';
+Wrap slow server work in `<Suspense>`. The shell streams immediately and the content follows when it's ready:
 
-export function GET(request: NextRequest) {
-  const name = request.nextUrl.searchParams.get('name');
-  return Response.json({ hello: name ?? 'world' });
+```tsx
+import { Suspense } from "@wular/pnext";
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading comments…</p>}>
+      <Comments />
+    </Suspense>
+  );
 }
 ```
 
-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
+### APIs and everything else
 
-`pnext dev`, `build`, and `typegen` generate route types in `.pnext/types`; import typed route props from `#gen/app/...`.
+A `route.ts` file is an HTTP handler:
 
-## Benchmarks
-
-```sh
-bun bench
+```ts
+// app/api/users/route.ts
+export async function GET(request: NextRequest) {
+  return Response.json(await listUsers());
+}
 ```
 
-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.
+- `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 more
 
-## Reference
+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)
 - [Routing](./reference/routing.md)
-- [Metadata](./reference/metadata.md)
+- [Navigation](./reference/navigation.md)
 - [Rendering](./reference/rendering.md)
+- [Metadata](./reference/metadata.md)
 - [CSS](./reference/css.md)
 - [Environment Variables](./reference/env.md)
-- [Compatibility](./reference/compat.md)
-- [Typegen](./reference/typegen.md)
 - [Config](./reference/config.md)
+- [Typegen](./reference/typegen.md)
+- [Compatibility](./reference/compat.md)
 - [Performance](./reference/performance.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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",