@thomas.f/prnext 0.1.16-alpha → 0.1.18-alpha

package/docs/ai/compatibility.md

@@ -0,0 +1,275 @@
+# Compatibility and migration
+
+[AI documentation index](../../AI.md)
+
+## Treat compatibility as a checked contract
+
+PRNext adapts many public Next.js conventions; it is not a drop-in implementation
+of every Next.js version. Package installation, a recognized import or a green
+source audit does not prove an application works. The installed package's
+metadata, declarations, diagnostics and executable behavior are the authority
+for this release. Do not use an old repository checklist to override them.
+
+Common supported areas include App/Pages routing, React Server Components,
+Server Actions, request APIs, navigation, route metadata, supported cache APIs,
+CSS Modules and the project's PostCSS pipeline. Scope varies by runtime and
+option. Advanced parallel/intercepting routing, custom webpack/loaders, package
+transpilation, image/font tooling and caching deserve targeted build and browser
+tests. Support for one configuration shape does not imply support for all
+upstream plugin behavior.
+
+## Instrumentation and tracing
+
+Use a single `instrumentation.ts`, `.js`, `.mjs` or `.cjs` at the project root
+or in `src`. Export an optional async `register()` for runtime initialization
+and an optional async `onRequestError(error, request, context)` for reporting.
+The `Instrumentation.onRequestError` type is exported from PRNext's root API.
+`process.env.NEXT_RUNTIME` distinguishes `nodejs` and `edge`; conditional imports
+keep Node SDKs out of an Edge bundle. Registration runs once per server realm,
+including the separate RSC realm, before application requests. A production
+prerender does not run the runtime startup hook. Request-time ISR and PPR
+regeneration initialize their server realm and report failures through the same
+hooks. Repeated propagation of an RSC error to the HTML worker does not report
+the same error again.
+
+```ts
+import type { Instrumentation } from '@thomas.f/prnext'
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./observability.node')
+  }
+}
+
+export const onRequestError: Instrumentation.onRequestError = async (
+  error, request, context
+) => {
+  await reportError(error, request, context)
+}
+```
+
+`reportError` above is an application function, not a PRNext API. Initialization
+has a 30-second budget. Each error hook has a five-second budget; reporting
+failure does not replace the application failure. Redirect/not-found control
+signals are excluded. Hooks receive request information: the application owns
+redaction before sending that information to a third party.
+
+For built-in correlated traces, explicitly set
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to an OTLP HTTP collector's complete traces
+URL and `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json`. Alternatively,
+`OTEL_EXPORTER_OTLP_ENDPOINT` supplies a base URL with `/v1/traces` appended.
+`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (or general
+`OTEL_EXPORTER_OTLP_HEADERS`) and `OTEL_SDK_DISABLED=true` are supported. Keep
+exporter credentials in the server environment. This built-in path supports
+HTTP JSON, not gRPC or HTTP protobuf; use your own SDK for other protocols.
+
+Native HTTP spans cover static and dynamic responses through body completion
+or cancellation. Node, RSC and fetch spans share W3C trace context. Export queues
+are bounded and telemetry is best effort; an unavailable collector does not
+block a site response. Built-in span attributes exclude bodies, cookie values,
+query strings and authorization headers. An application-installed
+`@opentelemetry/api` can use the same parent context when its SDK installs a
+context manager in `register`. No SDK is installed automatically, and this does
+not certify every vendor integration.
+
+## Production bytes and navigation
+
+Production CSS Modules use deterministic compact class and animation names.
+Global classes and declared composition exports retain their meaning; development
+keeps readable names. Internal JavaScript exports are shortened by the selected
+compiler, while public exports and dynamic imports keep their interfaces. Asset
+hashes and source maps remain compiler-owned.
+
+App navigation can negotiate binary differential Flight responses. Every request
+still runs fresh rendering and access checks. The server retains at most 64
+completed bases, 32 MiB in total, with a two-MiB per-base limit and 30-second
+expiry. Bases are keyed by deployment and credentials; an unknown, expired or
+incompatible base produces ordinary Flight. The browser retains one completed
+base, streams reconstructed bytes to React and can retry one failed differential
+navigation as a full GET. Server Actions are never replayed through this path.
+Per worker, at most eight captures and two encoders run together. Additional
+requests use ordinary Flight, keeping transient transport work bounded too.
+
+Configuration uses one `next.config.*` or `prnext.config.*` file and rejects
+unknown keys rather than ignoring them. React Compiler is available through an
+explicit `reactCompiler` option described below. `typedRoutes: true` is
+implemented through PRNext's generated route registry. Do not copy a full
+Next.js configuration template into a new application.
+
+The repository's reference tests build and run matching applications against
+Next.js 16.4.3, including mounted App navigation, form Actions and cookies,
+metadata, Pages locale routing, redirects, APIs and selected webpack loader
+contracts. These executable examples cover specific behavior; they do not
+certify every Next.js application or plugin. `NextRequest.nextUrl` understands
+data-route build IDs and locales, and request-cookie mutations synchronize the
+request header. Request cookies have different mutation results from response
+cookies; do not use them interchangeably.
+
+A locked real-application fixture additionally exercises Better Auth 1.7.14
+(email/password, session cookies and logout), Drizzle ORM 0.45.4 over SQLite
+through its proxy driver, next-intl 4.14.9 (server and client translations),
+and the MDX 3.1.1 webpack loader against Next.js 16.4.3. It covers authenticated
+Server Actions, user-owned rows, cookie/locale isolation, client navigation and
+Server Component `after()` callbacks. This is evidence for those workflows,
+not a guarantee for every plugin, provider or deployment configuration.
+
+PRNext-specific options such as `prerender` and `htmlOnly` are described in
+[Build and deployment](deployment.md). Do not pass them to an upstream Next.js
+build when comparing the two implementations.
+
+## TypeScript 7 and earlier compilers
+
+PRNext uses the application's installed TypeScript. TypeScript 7 runs through its
+official native `tsc` command for production checks, `prnext typecheck` and live
+development diagnostics. Install TypeScript normally, including its platform
+optional dependencies. PRNext does not download a compiler during a build.
+TypeScript 5 and 6 retain their compiler API integration.
+
+Checks use `--noEmit` and keep incremental compiler state in an owned temporary
+directory. Development reports updated errors and clears fixed diagnostics;
+new source files and configuration changes restart the native watch generation.
+`typedRoutes` also supports native TypeScript and preserves JSONC comments when
+adding its generated declaration to the config. Compiler support does not imply
+that every application is ready for TypeScript 7's own language/config changes.
+
+## React Compiler
+
+Enable the bundled official React Compiler in the project's existing config:
+
+```js
+export default {
+  reactCompiler: true,
+};
+```
+
+No separate compiler installation is required. The default is disabled;
+`reactCompiler: false` preserves the uncompiled component path. Enabled builds
+optimize project-owned browser components in both Pages and App applications,
+in development and production. App Client Components also use the transform in
+their isolated server-rendering graph. The Pages server graph stays uncompiled,
+including APIs, custom Document code and data-loader utilities, so ordinary
+server functions never acquire client-only memoization hooks. React Server
+Components, Server Action modules, PRNext internals, generated entrypoints and
+npm packages are not compiled. Keep the matching React 19 peer versions required
+by the installed framework.
+
+Ordinary `.mts`/`.cts` hook helpers can be optimized; server/client directives
+in those extensions remain unsupported. Decorated `.mts`/`.cts` utility modules
+keep their native compilation path while importing React components can still
+be optimized.
+
+For gradual adoption, use `reactCompiler: { compilationMode: 'annotation' }`, then
+put `"use memo";` at the beginning of each component or hook to optimize. In
+either mode, `"use no memo";` excludes an individual function. Supported object
+options are `compilationMode: 'infer' | 'annotation'`,
+`panicThreshold: 'none' | 'critical_errors' | 'all_errors'` and `target: '19'`.
+Defaults are `'infer'`, `'none'` and `'19'`; other fields are rejected.
+
+After a successful build, inspect the compiler's actual results:
+
+```sh
+prnext compiler
+prnext compiler --json
+```
+
+The report names observed functions, their project-relative files, optimization
+or skip status, and the compiler's reasons. These are transform decisions;
+server-code removal and tree shaking can later omit a function from the browser
+bundle. Cached transforms retain their
+diagnostics and are identified as reused. Browser and server graphs do not
+inflate the function count. An incremental build can reuse graph inputs without
+observing every transform; the report states that scope rather than claiming
+complete application coverage. Disabled compilation is reported explicitly.
+The report describes the last successful build, stays outside public assets and
+does not include source code. A failed build preserves the previous report.
+
+The compiler can skip code that cannot be safely optimized. Follow the Rules of
+React and check actual behavior rather than assuming every component was
+compiled. It reduces repeated component work; it does not guarantee faster
+server responses, smaller JavaScript or a specific speed multiplier. Validate
+hydration, interactions and Fast Refresh in the application, then compare a
+production build with the option enabled and disabled. Compilation adds build
+work; PRNext caches pure transforms with their compiler version and settings.
+
+See the [official React Compiler documentation](https://react.dev/learn/react-compiler).
+
+Only explicit private Next.js import adapters are supported. Do not add arbitrary
+`next/dist/...` imports or install another Next runtime to satisfy one: isolate
+or replace the incompatible dependency, retain the original framework where
+needed, and describe the limitation honestly.
+
+## Migrate conservatively
+
+Use the project's existing package manager. For npm, install the intended
+published PRNext release and its matching React peers, then inspect the dry run:
+
+```sh
+npm i --save-exact @thomas.f/prnext react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
+npx --no-install prnext migrate --dry-run
+npx --no-install prnext migrate --check --json
+```
+
+Review scripts, manager/workspace detection, configuration and reported source
+conflicts. When the plan is correct:
+
+```sh
+npx --no-install prnext migrate
+npx --no-install prnext check --json
+npx --no-install prnext typecheck
+npx --no-install prnext build
+```
+
+Migration changes selected scripts/dependencies, backs up package files and
+existing lockfiles, and keeps Next.js and application source. Public `next/*`
+imports can remain. Do not remove Next, replace all imports or recreate the
+application without a separate need.
+
+Installation honors npm, pnpm and Yarn Classic/Berry and the owning workspace
+root. Conflicting managers, unsafe filesystem entries and unlisted workspaces
+can block automatic install. `migrate --no-install` prepares the manifest for
+manual manager execution. Custom shell scripts may require a manual edit.
+An installation failure attempts safe manifest/lockfile restoration; it cannot
+roll back every dependency directory or manager cache. Never solve peer conflicts
+by silently adding `--force` or `--legacy-peer-deps`.
+
+`migrate --check` audits without applying a migration. Configuration evaluation
+can run project code, and installed custom loaders still require a real build.
+The audit is not a sandbox for untrusted projects.
+
+## Compare running applications
+
+Start the original application and the candidate on separate available ports.
+Create `paths.json` with representative concrete URLs:
+
+```json
+["/", "/products/demo", "/api/health"]
+```
+
+Then compare public GET responses:
+
+```sh
+prnext migrate --check --against http://localhost:3000 --candidate http://localhost:3001 --routes paths.json
+```
+
+The comparison does not authenticate or follow redirects. It compares response
+samples, including status, content type and selected body semantics; it does not
+prove hydration, styling, actions or all dynamic routes. Visit important routes
+in a real browser, test authorized and unauthorized states, and run the existing
+application tests. Keep the original setup available until the candidate is
+actually verified. Timings from this comparison are not controlled benchmarks.
+
+## Boundaries that often matter
+
+React server/client directives in `.mts`/`.cts` are rejected; use `.ts`/`.tsx`.
+App Route Handlers use Web Request/Response, while Pages APIs retain their own
+request/response contract. App and Pages router hooks are not interchangeable.
+Edge code cannot assume Node APIs or Node-only package behavior.
+
+HTTP/1 WebSockets can tunnel through supported external HTTP(S) rewrites and
+hosting gateways; App/Pages handlers do not gain a WebSocket server API. Static
+imports accept completed public browser output, not another framework's SSR
+server. See [Deployment](deployment.md) before choosing an adapter.
+
+When a feature is missing, give its exact failing API/option and a supported
+alternative. Do not claim full compatibility, invent a replacement method or
+mask the error with an empty shim.

package/docs/ai/data.md

@@ -0,0 +1,288 @@
+# Request data, actions and caching
+
+[AI documentation index](../../AI.md)
+
+## Request context
+
+Use server request APIs only while handling a PRNext request. Await `headers()`
+and `cookies()` from `next/headers`. Headers are read-only; cookie writes belong
+in a Server Action or Route Handler before response headers commit. Do not read
+the current request at module initialization or stash request data in a
+process-global variable.
+
+The following complete example stores a non-sensitive display preference. It is
+not an authentication or session implementation.
+
+### `app/preferences/actions.ts`
+
+```ts
+'use server';
+
+import { cookies } from 'next/headers';
+import { revalidatePath } from 'next/cache';
+
+export async function saveTheme(form: FormData) {
+  const theme = form.get('theme');
+  if (theme !== 'light' && theme !== 'dark') throw new Error('Invalid theme');
+  const store = await cookies();
+  store.set('theme', theme, { httpOnly: true, sameSite: 'lax', path: '/' });
+  revalidatePath('/preferences');
+}
+```
+
+### `app/preferences/page.tsx`
+
+```tsx
+import { cookies } from 'next/headers';
+import { saveTheme } from './actions';
+
+export default async function Preferences() {
+  const store = await cookies();
+  const theme = store.get('theme')?.value === 'dark' ? 'dark' : 'light';
+  return <main>
+    <h1>Preferences</h1>
+    <p>Current theme: {theme}</p>
+    <form action={saveTheme}>
+      <select name="theme" defaultValue={theme} aria-label="Theme">
+        <option value="light">Light</option>
+        <option value="dark">Dark</option>
+      </select>
+      <button type="submit">Save</button>
+    </form>
+  </main>;
+}
+```
+
+Server Actions accept untrusted input even when invoked through a form you
+rendered. Check authentication, authorization and input on every protected
+mutation. For real session cookies, use the application's session library and
+production HTTPS policy, including appropriate secure cookie settings.
+
+## Fetch deliberately
+
+Choose freshness explicitly. Request-specific or sensitive reads normally need
+`fetch(url, { cache: 'no-store' })`. Shared public data can opt into
+`cache: 'force-cache'` and `next: { revalidate: seconds, tags: [...] }`. The
+`next` extension belongs to PRNext's server fetch integration, not browser fetch.
+Check `response.ok` and validate the returned data before using it.
+
+Under the default route configuration, an ordinary fetch or `next.tags` alone
+does not request persistent caching. Route configuration can change defaults;
+inspect it before diagnosing a cache. Avoid conflicting `cache` and `revalidate`
+options. A successful fetch cache hit is different from cached HTML, a browser
+router cache hit or a compiler cache hit.
+
+`unstable_cache` caches JSON-serializable function results. A runnable public-data
+example:
+
+### `lib/catalog.ts`
+
+```ts
+import { unstable_cache } from 'next/cache';
+
+export const readCatalog = unstable_cache(
+  async () => [{ id: 'demo', name: 'Demo product' }],
+  ['public-catalog-v1'],
+  { tags: ['catalog'], revalidate: 60 },
+);
+```
+
+The static array stands in for a real server-side data read. Do not perform
+mutations in the cached callback. Read cookies/headers outside `unstable_cache`
+and pass required values as arguments. Include tenant/user identity in any
+appropriate cache key and authorize before access; never treat a shared cache as
+a session store. Avoid caching private data unless its isolation is deliberate
+and tested. Changes in closed-over values need explicit key parts or arguments.
+
+## Invalidate in the mutation
+
+`revalidatePath('/preferences')` invalidates a concrete path. A dynamic pattern
+requires its kind, such as `revalidatePath('/products/[slug]', 'page')`.
+`revalidateTag('catalog', 'max')` marks tagged data stale for revalidation;
+`updateTag('catalog')` expires it for read-your-own-writes in a Server Action.
+`updateTag` is action-only; path/tag revalidation also supports Route Handlers.
+Perform the underlying successful write before invalidating its cache.
+
+Invalidation APIs are rejected during rendering, inside a cached callback and
+after response headers have been sent. They do not delete unrelated build caches
+or restart the server. Custom cache handlers can delegate these semantics; do
+not infer their hit rate from PRNext's native-cache diagnostics.
+
+The installed implementation also has `cacheComponents`, `'use cache'`,
+`cacheLife` and `cacheTag` support. These are additional cache contracts; do not
+enable them to silence a request-context error or assume their complete upstream
+behavior. Keep a working `unstable_cache` or fetch solution unless the project
+needs a different model.
+
+## Navigation stages
+
+Enable `cacheComponents: true` and `partialPrefetching: true` to separate runtime
+App Shell work from per-link prefetch work and actual navigation work:
+
+```jsx
+import { Suspense } from 'react';
+import { navigation, prefetch } from 'next/cache';
+
+async function Recommendations() {
+  await prefetch();
+  return <div>{await getCachedRecommendations()}</div>;
+}
+
+async function ExpensiveReport() {
+  await navigation();
+  return <div>{await getCachedReport()}</div>;
+}
+
+export default function Page() {
+  return <>
+    <Suspense fallback={<p>Loading recommendations</p>}><Recommendations /></Suspense>
+    <Suspense fallback={<p>Loading report</p>}><ExpensiveReport /></Suspense>
+  </>;
+}
+```
+
+Define and authorize the application-specific data functions above. Call gates
+before invoking a cached function, never inside its cached scope. Both gates
+require Cache Components. Static prerenders continue through them, so static
+output can already contain the result. Without partial prefetching, `prefetch()`
+has no effect and an explicit `Link prefetch={true}` requests the full route.
+
+A default Link requests the shell. `prefetch={true}` permits per-link work;
+content below `navigation()` waits for the navigation. Runtime previews are
+private, size-bounded and tied to the request's authorization identity. They do
+not authorize a subsequent navigation.
+Uncached runtime fetches and `connection()` remain deferred during speculative
+rendering. Put reusable I/O in a cached function to make it eligible for an
+earlier stage; a gate does not itself cache data.
+
+Pages and layouts may export `ensureStatic = 'shell'`, `'prefetch'` or
+`'navigation'`. Earlier stages are included in stricter levels. A descendant
+cannot weaken a parent; `false` conflicts with a static requirement elsewhere
+in the route. `'auto'` adds no requirement. Client Component exports are rejected.
+`'shell'` and `'prefetch'` request static output for those stages without adding
+a separate full-route build check. `'navigation'` validates complete static
+server output during build and development, including request APIs beneath
+Suspense, metadata and complete dynamic parameter sets. It requires nonempty,
+complete `generateStaticParams()` results for dynamic routes. All levels require
+Cache Components; shell/prefetch levels need partial prefetching to select stages.
+
+## Shared Redis Cache Components
+
+The optional first-party Redis handler shares `'use cache'` results across Node
+processes. Install `@redis/client@^6.3.0` only in applications using it; a normal PRNext
+installation and generated project do not require Redis.
+
+### `redis-handler.mjs`
+
+```js
+import { createRedisCache } from '@thomas.f/prnext/cache/redis';
+
+export default createRedisCache({
+  namespace: 'my-app-production-v1',
+  urlEnv: 'REDIS_URL',
+});
+```
+
+### `prnext.config.mjs`
+
+```js
+export default {
+  cacheComponents: true,
+  cacheHandlers: { remote: './redis-handler.mjs' },
+};
+```
+
+### `app/catalog/read.ts`
+
+```ts
+import { cacheLife, cacheTag } from 'next/cache';
+
+export async function readCatalog() {
+  'use cache: remote';
+  cacheLife('hours');
+  cacheTag('catalog');
+  return [{ id: 'demo', name: 'Demo product' }];
+}
+```
+
+Set the Redis URL in the server's runtime environment. It is not embedded in the
+handler bundle. Replicas sharing results need the same namespace and compatible
+build output. Use separate namespaces for unrelated apps, environments and
+incompatible deployments. This factory handles Cache Components. The separate
+incremental factory below handles native HTML/ISR, fetch and `unstable_cache`.
+
+Cache fills use a bounded cross-process lease. Atomic tag generations prevent a
+fill invalidated while running, or an expired lease owner, from publishing old
+data. Soft tag invalidation retains stale-while-revalidate behavior; immediate
+expiration prevents another replica from reading the old entry. Losing the tag
+registry invalidates existing entries rather than resurrecting them.
+
+Values are limited to 2 MiB, metadata to 64 KiB and each entry to 256 tags.
+The tag registry is bounded; excess cardinality conservatively invalidates the
+namespace. Default retention is at most seven days. Defaults use a 30-second
+lease, a 2.5-second fill wait and one-second command timeout. Reads can fall back
+to fresh computation on cache failure; invalidation failures remain errors.
+Cached callbacks must be safe to execute more than once after timeout or outage:
+leases reduce duplicate work, not provide exactly-once business operations.
+
+An already connected node-redis client can be supplied as `client`; its lifecycle
+remains the application's responsibility. Otherwise the handler connects lazily
+and owns its client. Use Redis appropriate for the application's availability,
+access controls and data sensitivity; a shared cache is not an authorization
+boundary or a durable database.
+
+## Shared Redis pages and request data
+
+Configure `cacheHandler` with the constructor returned by the incremental factory:
+
+```js
+// incremental-redis.mjs
+import { createRedisIncrementalCache } from '@thomas.f/prnext/cache/redis';
+export default createRedisIncrementalCache({ namespace: 'my-app-production' });
+```
+
+```js
+// prnext.config.mjs
+export default {
+  cacheHandler: './incremental-redis.mjs',
+  cacheMaxMemorySize: 0,
+};
+```
+
+Set `REDIS_URL` at runtime and install the optional `@redis/client@^6.3.0` client.
+The same configuration works for App and Pages HTML/ISR, static Route Handlers,
+cacheable `fetch` and `unstable_cache`. It does not cache private dynamic pages.
+Replicas must use compatible builds and share an application-specific namespace.
+Cache Components still select their own `cacheHandlers`; both factories may use
+the same namespace to share tag invalidations.
+
+The runtime acquires a shared generation lease before rendering, checks for a
+winner's result after waiting and carries that lease through publication. An
+invalidation or expired lease rejects late writes atomically. Runtime reads and
+publication remain bounded; unavailable Redis can prevent a page regeneration
+from succeeding. A shared cache is not a durable database or an exactly-once
+execution mechanism. Keep producers safe to retry.
+
+Incremental entries preserve Buffer and Map values, have a 16 MiB serialized
+limit and use V8-major-specific keys. The default generation lease is 60 seconds;
+`leaseMs` can be configured up to 120 seconds. Configure it for the expected
+generation duration. The default maximum storage age remains seven days.
+New cacheHandler builds include a native generation-lease capability check;
+use the matching PRNext native binary and rebuild existing output.
+
+## Background work and durable data
+
+`after()` from `next/server` is supported in Node Server Components (including
+layouts and metadata), Route Handlers and Server Actions. It runs tracked
+callbacks after the response completes or disconnects; static renders execute
+them during the build. Edge lifecycles remain unsupported. In a Server Component,
+read request data before registering the callback and capture the needed values:
+`headers()`, `cookies()` and `draftMode()` inside that callback are rejected.
+Route Handler and Action callbacks can read their retained request context.
+Cookie writes and path/tag invalidation are rejected after the response;
+invalidate before returning from the mutation.
+
+Tracked callbacks are bounded by the route's `maxDuration` and shutdown
+deadlines; forced termination can interrupt them. Use an external durable queue
+for work that must survive a restart. Module globals, local runtime caches and
+temporary files are not substitutes for a database or durable job store.