npm - @wular/pnext - Versions diffs - 0.0.6 → 0.0.8 - Mend

@wular/pnext 0.0.6 → 0.0.8

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 (35) hide show

package/README.md +12 -6
package/bin/pnext +5 -0
package/package.json +1 -1
package/reference/compat.md +86 -21
package/reference/config.md +40 -93
package/reference/css.md +40 -35
package/reference/dev.md +25 -32
package/reference/env.md +18 -20
package/reference/getting-started.md +132 -0
package/reference/metadata.md +26 -41
package/reference/navigation.md +58 -105
package/reference/performance.md +21 -142
package/reference/rendering.md +73 -70
package/reference/routing.md +87 -97
package/reference/typegen.md +21 -27
package/src/api/client-navigation.ts +11 -8
package/src/api/link.tsx +5 -3
package/src/cli/analyze.ts +103 -48
package/src/cli/create.ts +1 -1
package/src/cli/index.ts +6 -0
package/src/client/build.ts +10 -2
package/src/client/entry.ts +13 -9
package/src/client/router/events.ts +15 -0
package/src/client/router/runtime.ts +40 -9
package/src/client/router/types.ts +5 -0
package/src/config.ts +18 -1
package/src/dev/server.ts +2 -2
package/src/render/renderer.ts +11 -0
package/src/render/static-slots-revive.ts +65 -0
package/src/render/static-slots.ts +3 -54
package/src/routing/href.ts +19 -1
package/src/runtime/loader.ts +3 -1
package/src/runtime/vendor.ts +5 -4
package/src/types.ts +5 -1
package/reference/overview.md +0 -35

package/reference/routing.md CHANGED Viewed

@@ -1,39 +1,46 @@
 # Routing
-## Files
+Routes come from the file tree under `app/`. Directories make the URL path, and a `page` file inside one renders it as its default export.
-- `app/**/page` defines a UI route.
-- `app/**/layout` exports metadata and can wrap descendant pages.
-- `app/**/route` defines HTTP handlers.
-- `proxy` or `middleware` runs before route matching.
-- `app/**/loading` defines a Suspense fallback for the segment.
-- `app/**/error` defines fallback UI for server render failures in the segment.
-- `app/**/not-found` defines fallback UI.
+## Path patterns
-Convention files are matched across `.tsx`, `.ts`, `.jsx`, `.js`, and `.mjs`.
-`.tsx`/`.ts` are tried first, so an all-`.tsx` app resolves on the first
-candidate. Route handlers (`route`) match `.ts`, `.tsx`, `.js`, `.mjs`.
+| Directory                  | Serves                                  |
+| -------------------------- | --------------------------------------- |
+| `app/about/`               | `/about`                                |
+| `app/users/[id]/`          | `/users/:id`                            |
+| `app/docs/[...slug]/`      | `/docs/*`                               |
+| `app/docs/[[...slug]]/`    | `/docs` and `/docs/*`                   |
+| `app/(marketing)/pricing/` | `/pricing`, the group adds no segment   |
+| `app/dashboard/@team/`     | a slot of `/dashboard`, no path segment |
-## Segments
+## Convention files
-- `app/about/page.tsx` -> `/about`
-- `app/users/[id]/page.tsx` -> `/users/:id`
-- `app/docs/[...slug]/page.tsx` -> `/docs/*`
-- `app/docs/[[...slug]]/page.tsx` -> matches `/docs` AND `/docs/*` (the base path is included)
-- `app/(marketing)/pricing/page.tsx` -> `/pricing`
-- `app/dashboard/@team/page.tsx` -> a `@slot` directory adds no path segment; it is rendered as a slot of `/dashboard`
+| File           | What it does                                              |
+| -------------- | --------------------------------------------------------- |
+| `page`         | Renders a UI route.                                       |
+| `layout`       | Exports metadata and can wrap descendant pages.           |
+| `route`        | Defines HTTP handlers.                                    |
+| `loading`      | Suspense fallback for the segment.                        |
+| `error`        | Fallback UI when server rendering throws in the segment.  |
+| `not-found`    | Fallback UI for `notFound()` and unmatched URLs.          |
+| `template`     | Wraps children like a layout, but re-renders per request. |
+| `default`      | Fallback for a parallel slot with no page match.          |
+| `global-error` | Replaces the whole document for an uncaught root error.   |
-### Intercepting markers
+Convention files are matched across `.tsx`, `.ts`, `.jsx`, `.js`, and `.mjs`, with the TypeScript extensions tried first. Route handlers are the exception: they do not match `.jsx`. A proxy file lives at the project root rather than in a segment, and is covered under [Proxy](#proxy).
-A marker prefixes a segment to intercept a route from another level. The marker
-is stripped from the resulting path. See [Intercepting routes](#intercepting-routes).
+Behavior worth knowing:
-- `(.)segment` -> same level.
-- `(..)segment` -> one level up.
-- `(..)(..)segment` -> two levels up.
-- `(...)segment` -> from the app root.
+- `loading`: static builds wait for the final HTML, while dev and server responses can stream the fallback first.
+- `error`: receives `error`, `reset`, and `unstable_retry`. Both callbacks refresh the current route in `compat.next` apps.
+- `not-found`: `pnext build` also writes `404.html` when the app root has one.
+- `global-error`: renders its own `<html>` and `<body>`, so pnext serves that markup instead of the normal document shell. A nearer error boundary wins, and a `"use client"` directive opts the file out.
+- `template`: nesting order is layout, then template, then children. A segment with no layout still applies its template.
+- `forbidden` and `unauthorized`: experimental `compat.next` boundaries that render 403 and 401 responses. Without compat, the thrown errors take the normal error path. The `forbidden()` and `unauthorized()` functions are core exports either way. See [Navigation](./navigation.md#auth-interrupts).
-## Page Props
+To leave a route, use `redirect()` or `notFound()`. See [Navigation](./navigation.md#redirects-and-not-found).
+## Page props
 Pages receive explicit props:
@@ -45,67 +52,71 @@ type PageProps<P = Record<string, string | string[]>> = {
 }
 ```
-Request data is read from `props.request`.
+Read request data from the request prop. Typed per-route versions of these props are generated for you; see [Type Safety](./typegen.md).
-## Route Handlers
+## Route handlers
-Route handlers use the Next-compatible `(request, context)` shape:
+A `route` file exports one function per HTTP method. The request extends the standard `Request` with convenience access for cookies and `nextUrl`, and the context carries the route params.
 ```ts
-import type { RouteContext } from '#gen/app/api/users/[id]/route'
-import type { NextRequest } from '@wular/pnext/server'
-export async function GET(request: NextRequest, { params }: RouteContext) {
+export async function GET(
+  request: NextRequest,
+  { params }: RouteContext,
+) {
   const { id } = await params
-  return Response.json({
-    id,
-    q: request.nextUrl.searchParams.get('q'),
-  })
+  return Response.json({ id })
 }
 ```
-`request` is a `NextRequest` compatible object. It extends the standard `Request` with convenience access for cookies and `nextUrl`.
-If `OPTIONS` is not exported, pnext returns an automatic `OPTIONS` response with an `Allow` header. Unsupported methods return `405 Method Not Allowed` with the same `Allow` header.
+If a handler does not export `OPTIONS`, pnext answers with an automatic response carrying an `Allow` header. Unsupported methods get a 405 with that same header.
-Static `GET` route handlers are written as files during `pnext build`. Dynamic route handlers can export `params()` to write selected param outputs at build time.
+Static `GET` handlers are written as files during the build. A dynamic handler can export `params()` to write selected param outputs at build time.
-`generateStaticParams()` is supported in Next compat mode.
+## Static and dynamic routes
-## Route Rendering
+pnext infers rendering from what a route uses:
-pnext infers route rendering separately from hydration:
+- Static: no dynamic params and no request prop usage.
+- Dynamic: request prop usage or dynamic route segments.
-- `static`: no dynamic params and no request prop usage.
-- `dynamic`: request prop usage or dynamic route segments.
+Segment config overrides the inference. Hydration is inferred separately, from `"use client"`.
-Route segment config overrides the inference. Hydration is controlled by `"use client"`.
+## Route segment config
-## Route Segment Config
-Pages, layouts, and route handlers can export segment config. Values must be literals — they are read from the source, not evaluated.
+Pages, layouts, and route handlers can export segment config. Values must be literals, because they are read from the source rather than evaluated.
 ```ts
 export const dynamic = 'force-dynamic'
 export const maxDuration = 60
 ```
-Recognized: `dynamic` (`auto` | `force-dynamic` | `force-static` | `error`), `revalidate` (a non-negative number or `false`), `fetchCache`, `dynamicParams`, `runtime` (`edge` | `nodejs`), `prefetch`, and `maxDuration`.
+- `dynamic`: `auto`, `force-dynamic`, `force-static`, or `error`.
+- `revalidate`: a non-negative number, or `false`.
+- `dynamicParams`: `false` restricts the route to its generated params.
+- `runtime`: `edge` or `nodejs`.
+- `maxDuration`: seconds, copied into the generated Vercel Node function metadata.
+- `fetchCache`: `auto`, `default-cache`, `only-cache`, `force-cache`, `force-no-store`, `default-no-store`, or `only-no-store`.
+- `prefetch`: `allow-runtime`, `partial`, or `unstable_eager`.
+- `unstable_instant`: experimental, described below.
+Config merges across the route's own file and its layout chain, leaf-first, so the nearest declaration wins. Two values behave differently: `force-dynamic` on any segment forces the whole route, and the lowest declared `revalidate` wins.
-Config merges across the route's own file and its layout chain, leaf-first: the nearest declaration wins, except `force-dynamic` (any segment forces the whole route) and `revalidate` (the lowest declared number wins).
+Setting `dynamicParams` to false applies to the dynamic segment declared by that file. When every dynamic segment has static params, requests must match a generated param tuple. Otherwise pnext drops the restriction and renders the route on demand. A page-level static params export makes this check apply to the complete param tuple.
-When building with `pnext build --adapter vercel`, `maxDuration` is copied to the generated Vercel Node function metadata.
+`unstable_instant` is experimental. Set it to `true` or to an object of samples to opt in, and a leaf `false` overrides a layout opt-in. A full prefetch of such a route uses sampled request data and leaves `connection()`-gated content out of that prefetch render.
-## File Conventions
+`experimental_ppr` is also experimental. For a request-using page without dynamic route segments, it records the page as a partial-prerendering candidate. See [Rendering](./rendering.md#experimental-partial-prerendering-and-cachecomponents).
-`proxy.ts` and `middleware.ts` run before static files, pages, and route handlers. Use `proxy.ts` for new code. `middleware.ts` is supported for compatibility. If both exist, `proxy.ts` wins.
+`preferredRegion` is a `compat.next`-only export. It accepts a string or string array and is written to compat deployment metadata.
+## Proxy
+A `proxy` file at the project root runs before static files, pages, and route handlers.
 ```ts
 import { NextResponse, type NextRequest } from '@wular/pnext/server'
-export const config = {
-  matcher: ['/admin/:path*'],
-}
+export const config = { matcher: ['/admin/:path*'] }
 export function proxy(request: NextRequest) {
   if (!request.cookies.has('session')) {
@@ -115,53 +126,32 @@ export function proxy(request: NextRequest) {
 }
 ```
-Supported responses:
-- `NextResponse.next()` continues to the matched static file, page, or route handler.
-- `NextResponse.redirect(url)` returns a redirect response.
-- `NextResponse.rewrite(url)` serves another path without changing the browser URL.
-- `new Response(...)` returns a custom response directly.
-`config.matcher` takes a string, a string array, or objects with `source` plus `has`/`missing` conditions (`header`, `query`, `cookie`, `host`). Patterns support exact paths, `:param`, `:path*`, and regex. With no `matcher`, every request runs through the proxy.
+Return one of:
-`loading.tsx` is used as the fallback for automatically wrapped server Suspense boundaries. Static builds wait for final HTML; dev and server responses can stream the fallback first.
+- `NextResponse.next()` to continue to the matched static file, page, or route handler.
+- `NextResponse.redirect(url)` for a redirect response.
+- `NextResponse.rewrite(url)` to serve another path without changing the browser URL.
+- `new Response(...)` for a custom response.
-`not-found.tsx` is rendered when a route calls `notFound()` or when no route matches. `pnext build` also writes `404.html` when root `app/not-found.tsx` exists.
+The matcher accepts a string, an array of strings, or objects with a source pattern plus `has` and `missing` conditions on header, query, cookie, and host. Patterns support exact paths, `:param`, `:path*`, and regex. Without a matcher, every request runs through the proxy.
-`global-error.tsx` at the app root replaces the entire document when an unhandled error reaches the root uncaught. It renders its own `<html>` and `<body>`, so pnext skips the normal document shell and serves its markup directly. It only takes over when no nearer `error.tsx` boundary catches first, and a `"use client"` directive opts the file out.
+A `middleware` file works the same way and is supported for compatibility. Use a proxy file for new code, and note that it wins if both exist.
-`redirect()` and `permanentRedirect()` stop rendering and return redirect responses. They can be called from pages, server components, route handlers, and server helpers used during rendering.
-Validate redirect targets that come from user input.
+## Static params
-`error.tsx` is rendered when server rendering throws. It receives `error`, `reset`, and `unstable_retry`; `reset()`/`unstable_retry()` refresh the current route in `compat.next` apps.
+Export `params()` from a dynamic route to choose which params `pnext build` writes as static HTML. See the typed example in [Type Safety](./typegen.md). Under `compat.next`, `generateStaticParams()` fills the same role when a module has no `params()` export.
-`template.tsx` wraps the segment's children like a layout, but the segment re-renders per request where a layout persists. Nesting order is layout > template > children. A segment without a layout still applies its template.
+## Parallel routes
-`default.tsx` is the fallback rendered for a parallel `@slot` that has no page match.
+A slot directory such as `@team` contributes no path segment. Its content is rendered and passed to the owning segment's layout as a prop named after the slot, alongside `children`. A slot uses its `page` when present, then its `default` fallback, and otherwise renders nothing. A slot's `loading` file wraps its content in a Suspense boundary.
-`forbidden.tsx` and `unauthorized.tsx` render at 403/401 when `forbidden()` / `unauthorized()` is thrown. These are COMPAT-only (require `compat.next`) and experimental (`authInterrupts`); without compat they fall through to the normal error page.
+## Intercepting routes
-### Parallel routes
+A marker prefixed to a segment intercepts a route from another level, and is stripped from the resulting path:
-A `@slot` directory (e.g. `@team`) contributes no path segment. Its content is rendered and passed to the owning segment's layout as a prop keyed by the slot name (without the `@`), alongside `children`. A slot uses its `page` when present, else its `default` fallback, else renders nothing. A slot's `loading` wraps its content in a Suspense boundary.
+- `(.)segment` intercepts from the same level.
+- `(..)segment` intercepts from one level up.
+- `(..)(..)segment` intercepts from two levels up.
+- `(...)segment` intercepts from the app root.
-### Intercepting routes
-An interception marker (`(.)`, `(..)`, `(..)(..)`, `(...)`) makes the route respond to soft navigations toward the marked target from the intercepting level, usually rendered into a parallel `@slot`. Hard requests render the non-intercepted target. Intercepting routes are always dynamic and never take static params.
-## Static Params
-Use `params()` on a dynamic route to choose params that `pnext build` should write as static HTML.
-Requests outside the returned list keep using dynamic rendering.
-```tsx
-import type { PageProps, StaticParams } from '#gen/app/users/[id]/page'
-export function params(): StaticParams {
-  return [{ id: 'ada' }, { id: 'grace' }]
-}
-export default async function Page({ params }: PageProps) {
-  return <p>{(await params).id}</p>
-}
-```
+The intercepting route answers soft navigations toward the marked target, usually rendering into a parallel slot. A hard request renders the non-intercepted target instead. Intercepting routes are always dynamic and never take static params.

package/reference/typegen.md CHANGED Viewed

@@ -1,14 +1,17 @@
 # Type Safety
-pnext generates route types from the `app/` tree. These types check route params, static params, route handlers, and typed navigation.
+pnext generates types from the `app/` tree so route params, static params, route handler context, and links are all checked.
-## Route Types
+## Route types
-Import generated types for the current route. pnext validates those exports against the route inferred from the file path, so a wrong param name, static param shape, or route handler context fails TypeScript.
+Each route imports the types generated for its own file path. pnext validates the exports against the route inferred from that path, so a wrong param name, a bad static param shape, or the wrong handler context fails TypeScript.
 ```tsx
 // app/users/[id]/page.tsx
-import type { PageProps, StaticParams } from '#gen/app/users/[id]/page'
+import type {
+  PageProps,
+  StaticParams,
+} from '#gen/app/users/[id]/page'
 export function params(): StaticParams {
   return [{ id: 'ada' }]
@@ -19,43 +22,28 @@ export default async function Page({ params }: PageProps) {
 }
 ```
-Route handlers use generated `RouteContext` for the second argument:
+A route handler takes its generated context type as the second argument.
 ```ts
 // app/users/[id]/route.ts
 import type { RouteContext } from '#gen/app/users/[id]/route'
 import type { NextRequest } from '@wular/pnext/server'
-export async function GET(request: NextRequest, { params }: RouteContext) {
+export async function GET(
+  request: NextRequest,
+  { params }: RouteContext,
+) {
   return Response.json({ id: (await params).id })
 }
 ```
 ## Links
-Typed links use typed `href` and `params`:
+`<Link>` and `href()` check their route template and params against the same generated types. See [Navigation](./navigation.md).
-```tsx
-import { Link } from '@wular/pnext/link'
-export function Nav() {
-  return (
-    <Link href="/users/[id]" params={{ id: 'ada' }}>
-      Ada
-    </Link>
-  )
-}
-```
-Use a normal `<a>` for external URLs or intentionally untyped links.
-## Generated Types
+## Setup
-`pnext dev` and `pnext build` refresh generated types automatically. Use `pnext typegen` to refresh them manually.
-Generated files live in `.pnext/types` and should not be edited. Include `.pnext/types/**/*.ts` in the app TypeScript project for editor and `tsc` visibility.
-Use a TypeScript path alias for generated imports:
+Apps from `pnext create` are already set up. The package ships the `@wular/pnext/config/ts/react.json` preset, which the scaffold puts in `extends` alongside the alias for generated types:
 ```json
 {
@@ -66,3 +54,9 @@ Use a TypeScript path alias for generated imports:
   }
 }
 ```
+Include `.pnext/types/**/*.ts` in the app TypeScript project so the editor and `tsc` can see the generated files. `pnext migrate` repoints existing include paths there, but it does not add the alias.
+## Regenerating
+The dev server and the build refresh generated types on their own. Run `pnext typegen` to refresh them by hand. The files live in `.pnext/types` and should not be edited.

package/src/api/client-navigation.ts CHANGED Viewed

@@ -163,18 +163,17 @@ export function useLinkStatus() {
 }
 function useLocation() {
-  const [location, setLocation] = useState(() => currentLocation())
+  // Read the URL live each render so any render pairs the address bar with its params;
+  // state is only the re-render trigger (unchanged-URL broadcasts bail out).
+  const location = currentLocation()
+  const [, setLocationKey] = useState(() => locationSignature(location))
   useEffect(() => {
     patchHistory()
     const listener = () =>
-      setLocation(previous => {
-        const next = currentLocation()
-        return previous.pathname === next.pathname &&
-          previous.search === next.search &&
-          previous.hash === next.hash
-          ? previous
-          : next
+      setLocationKey(previous => {
+        const next = locationSignature(currentLocation())
+        return previous === next ? previous : next
       })
     locationListeners().add(listener)
     window.addEventListener('popstate', listener)
@@ -191,6 +190,10 @@ function useLocation() {
   return location
 }
+function locationSignature(location: { pathname: string; search: string; hash: string }) {
+  return `${location.pathname}${location.search}${location.hash}`
+}
 function currentLocation() {
   if (!process.browser && typeof window === 'undefined') {
     return {

package/src/api/link.tsx CHANGED Viewed

@@ -1,7 +1,7 @@
 import { h, type ComponentChildren, type JSX } from 'preact'
 import { useEffect, useRef } from 'preact/hooks'
 import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from 'react'
-import { routeHref, type SearchInput } from '../routing/href'
+import { getDefaultPrefetchMode, routeHref, type SearchInput } from '../routing/href'
 import type { PrefetchMode, RouteParams, RoutePath } from '../types'
 export interface NavigateEvent {
@@ -36,7 +36,7 @@ export type LinkProps<Route extends RoutePath = RoutePath> = BaseLinkProps &
 export function Link<Route extends RoutePath>({
   href,
   params,
-  prefetch = 'visible',
+  prefetch,
   replace,
   scroll,
   search,
@@ -49,6 +49,8 @@ export function Link<Route extends RoutePath>({
   ...anchorProps
 }: LinkProps<Route>): ReactNode {
   const resolvedHref = routeHref(href, { params: params ?? {}, search, hash })
+  // A link's own prefetch prop wins; otherwise the app-wide config default.
+  const prefetchMode = prefetch ?? getDefaultPrefetchMode()
   const anchorRef = usePrefetchLifecycle(onPrefetchStart, onPrefetchFinish)
   return h(
     'a',
@@ -57,7 +59,7 @@ export function Link<Route extends RoutePath>({
       ref: anchorRef,
       href: resolvedHref,
       'data-pnext-link': true,
-      'data-prefetch': prefetch === false ? 'false' : prefetch,
+      'data-prefetch': prefetchMode === false ? 'false' : prefetchMode,
       'data-pnext-replace': replace ? 'true' : undefined,
       'data-pnext-scroll': scroll === false ? 'false' : undefined,
       onClick: event => {