@wular/pnext 0.0.19 → 0.0.21

package/src/cli/create.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { mkdir, readdir } from 'node:fs/promises'
 import path from 'node:path'
 import { bold, cyan, dim, green } from '../utils/ansi'
-import { pnextVersionRange } from '../utils/fs'
+import { latestPnextVersionRange } from '../utils/registry'
 import { formatDuration } from '../utils/verbose'
 
 export interface CreateAppOptions {
@@ -27,7 +27,7 @@ export async function createApp(dir: string | undefined, options: CreateAppOptio
   const name = sanitizePackageName(path.basename(target))
   console.log(`${cyan('▲')} ${bold('pnext create')} ${dim(`— scaffolding ${name}`)}\n`)
 
-  const files = scaffoldFiles(name)
+  const files = scaffoldFiles(name, await latestPnextVersionRange('create'))
   await Promise.all(
     Object.entries(files).map(([file, source]) => Bun.write(path.join(target, file), source)),
   )
@@ -112,7 +112,7 @@ function printNextSteps(dir: string, installed: boolean) {
   console.log(dim(`└${'─'.repeat(width + 2)}┘`))
 }
 
-function scaffoldFiles(name: string): Record<string, string> {
+function scaffoldFiles(name: string, pnextRange: string): Record<string, string> {
   return {
     'package.json': `${JSON.stringify(
       {
@@ -126,7 +126,7 @@ function scaffoldFiles(name: string): Record<string, string> {
         },
         dependencies: { preact: '^10' },
         devDependencies: {
-          '@wular/pnext': pnextVersionRange(),
+          '@wular/pnext': pnextRange,
           typescript: '^5',
           '@types/bun': '^1',
         },

package/src/cli/dev.ts

@@ -1,3 +1,5 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
 import { dim } from '../utils/ansi'
 import { moduleGenerationStats } from '../runtime/module-generations'
 import { markBoot, printBootTrace } from './boot/trace'
@@ -40,6 +42,7 @@ export async function dev(options: DevOptions = {}) {
   markBoot('dev:imports')
   const config = await loadConfig(options.root, { dev: true })
   markBoot('dev:config')
+  warnDuplicateSass(config.root, Boolean(config.compat?.next))
   const port = options.port ?? 3000
   const hostname = options.hostname ?? 'localhost'
   // A memory-triggered restart can briefly race the previous listener's
@@ -76,6 +79,26 @@ export async function dev(options: DevOptions = {}) {
   return server
 }
 
+/** Next's dev-only preflight warning for projects carrying both Sass implementations. */
+function warnDuplicateSass(root: string, nextCompat: boolean): void {
+  if (!nextCompat) return
+  const appRequire = createRequire(path.join(root, 'package.json'))
+  const installed = (name: string) => {
+    try {
+      appRequire.resolve(name)
+      return true
+    } catch {
+      return false
+    }
+  }
+  if (!installed('sass') || !installed('node-sass')) return
+  console.warn(
+    'Your project has both `sass` and `node-sass` installed as dependencies, but should only use one or the other. ' +
+      'Please remove the `node-sass` dependency from your project. ' +
+      ' Read more: https://nextjs.org/docs/messages/duplicate-sass',
+  )
+}
+
 // Every dev reload imports changed modules under fresh URLs, and the ES module
 // registry never evicts, so a long session pins every stale graph in memory.
 // Once RSS crosses the limit, trade a seconds-long restart (vendor bundles are

package/src/cli/migrate/package-json.ts

@@ -3,7 +3,8 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { pnextOptionalDependencyRange, pnextVersionRange } from '../../utils/fs'
+import { pnextOptionalDependencyRange } from '../../utils/fs'
+import { latestPnextVersionRange } from '../../utils/registry'
 import type { MigrationResult } from './report'
 
 const SEPARATORS = new Set(['&&', '||', ';', '|', '&'])
@@ -124,7 +125,7 @@ export async function migratePackageJson(
     }
   }
   if (!('@wular/pnext' in devDependencies) && !('@wular/pnext' in dependencies)) {
-    const versionRange = pnextVersionRange()
+    const versionRange = await latestPnextVersionRange('migrate')
     devDependencies['@wular/pnext'] = versionRange
     result.edits.push({
       file: 'package.json',

package/src/cli/migrate/report.ts

@@ -25,7 +25,7 @@ export interface ReportItem {
 export interface MigrationResult {
   edits: Edit[]
   reports: ReportItem[]
-  /** Files reading cookies()/headers()/draftMode() synchronously (Next 14 style). */
+  /** Files reading cookies()/headers()/draftMode() or params/searchParams synchronously (Next 14 style). */
   syncRequestApis: string[]
   /** Files importing next/font/google, which needs the `next-font` metadata package. */
   googleFontImports: string[]

package/src/cli/migrate/run.ts

@@ -66,7 +66,7 @@ async function createPnextConfig(root: string, result: MigrationResult, dryRun:
       legacy
         ? 'export default {\n' +
             '  compat: {\n' +
-            '    // Sync cookies()/headers() still work; migrate to `await` and drop this.\n' +
+            '    // Sync cookies()/headers()/params still work; migrate to `await` and drop this.\n' +
             '    next: { legacyRequestAPIs: true },\n' +
             '  },\n' +
             '};\n'
@@ -84,7 +84,7 @@ async function createPnextConfig(root: string, result: MigrationResult, dryRun:
 
 function reportSyncRequestApis(result: MigrationResult, existingConfig?: string) {
   result.reports.push({
-    title: 'Sync cookies()/headers() detected',
+    title: 'Sync cookies()/headers()/params detected',
     detail: existingConfig
       ? `Set compat: { next: { legacyRequestAPIs: true } } in ${existingConfig} to keep these working, then migrate to \`await\` and remove it. See https://pnext.dev/docs/compat`
       : 'Enabled compat.next.legacyRequestAPIs; migrate to `await` and remove it. See https://pnext.dev/docs/compat',

package/src/cli/migrate/scan.ts

@@ -23,6 +23,15 @@ const NEXT_HEADERS_IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]next\/headers['"]
 const REQUEST_APIS = new Set(['cookies', 'headers', 'draftMode'])
 const PROMISE_METHODS = new Set(['then', 'catch', 'finally'])
 const SPECIAL_PAGES = ['_app', '_document', '_error']
+// App-router segment files, the only place `params`/`searchParams` arrive as props.
+const SEGMENT_FILES = new Set(['page', 'layout', 'route', 'template', 'default'])
+// Every head whose match ENDS at the parameter list's `(` — default exports and generateMetadata.
+const SEGMENT_HEADS =
+  /export\s+default\s+(?:async\s+)?function\s*[\w$]*\s*\(|export\s+default\s+(?:async\s+)?\(|export\s+(?:async\s+)?function\s+generateMetadata\s*\(|export\s+const\s+generateMetadata\s*(?::[^=]*)?=\s*(?:async\s*)?\(/g
+// Route-handler methods take `{ params }` as their SECOND parameter (the context object).
+const ROUTE_HANDLER_HEADS =
+  /export\s+(?:async\s+)?function\s+(?:GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)\s*\(|export\s+const\s+(?:GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)\s*(?::[^=]*)?=\s*(?:async\s*)?\(/g
+const SYNC_PROPS = ['params', 'searchParams'] as const
 
 export async function scanSources(root: string, result: MigrationResult) {
   const { SHIMMED_NEXT_DIST_PATHS } = await import('../../compat/aliases')
@@ -57,7 +66,9 @@ export async function scanSources(root: string, result: MigrationResult) {
       // package, so only it earns the dependency.
       if (specifier === 'next/font/google') result.googleFontImports.push(relative)
     }
-    if (readsRequestApiSynchronously(text)) result.syncRequestApis.push(relative)
+    if (readsRequestApiSynchronously(text) || readsSyncSegmentProps(file, text)) {
+      result.syncRequestApis.push(relative)
+    }
   }
 
   if (deepImports.length > 0) {
@@ -111,6 +122,122 @@ function readsRequestApiSynchronously(text: string): boolean {
   return false
 }
 
+/**
+ * A segment file whose default export (or generateMetadata) takes `params`/`searchParams` the Next 14
+ * way — annotated as a plain object rather than a Promise, or destructured and read without `await`.
+ * Precision over recall: an unresolvable annotation, an awaited read, or a `params` key anywhere other
+ * than the parameter list (an axios `{ params: { page } }` option bag) never counts.
+ */
+export function readsSyncSegmentProps(file: string, text: string): boolean {
+  const extension = path.extname(file)
+  if (!SEGMENT_FILES.has(path.basename(file, extension))) return false
+  return readsHeadProps(text, SEGMENT_HEADS, 0) || readsHeadProps(text, ROUTE_HANDLER_HEADS, 1)
+}
+
+function readsHeadProps(text: string, heads: RegExp, index: number): boolean {
+  for (const head of text.matchAll(heads)) {
+    const list = balanced(text, head.index + head[0].length - 1, '(', ')')
+    const parameter = (splitTopLevel(list)[index] ?? '').trim()
+    if (parameter && readsPropsSynchronously(parameter, text)) return true
+  }
+  return false
+}
+
+function readsPropsSynchronously(parameter: string, text: string): boolean {
+  const colon = topLevelIndex(parameter, ':')
+  const binding = (colon < 0 ? parameter : parameter.slice(0, colon)).trim()
+  const annotation = colon < 0 ? '' : parameter.slice(colon + 1).trim()
+  const destructured = binding.startsWith('{') ? destructuredKeys(binding) : null
+  for (const prop of SYNC_PROPS) {
+    if (destructured && !destructured.has(prop)) continue
+    if (annotation) {
+      const declared = propertyType(annotation, text, prop)
+      if (declared && !/^Promise\s*</.test(declared)) return true
+      continue
+    }
+    // Untyped JS: a destructured binding read without `await`, or `props.params` read without one.
+    if (destructured) {
+      if (!new RegExp(`await\\s+${prop}\\b`).test(text)) return true
+    } else if (/^[\w$]+$/.test(binding)) {
+      const reads = text.matchAll(new RegExp(`(await\\s+)?\\b${binding}\\.${prop}\\b`, 'g'))
+      if ([...reads].some(read => !read[1])) return true
+    }
+  }
+  return false
+}
+
+/** The declared type of `prop` inside an inline object annotation or a locally declared type/interface. */
+function propertyType(annotation: string, text: string, prop: string): string | undefined {
+  let body: string | undefined
+  if (annotation.startsWith('{')) {
+    body = balanced(annotation, 0, '{', '}')
+  } else {
+    const name = /^[\w$]+/.exec(annotation)?.[0]
+    body = name ? localTypeBody(name, text) : undefined
+  }
+  if (!body) return undefined
+  return new RegExp(`(?:^|[{;,\\n])\\s*${prop}\\s*\\??\\s*:\\s*([^;,\\n]+)`).exec(body)?.[1]?.trim()
+}
+
+function localTypeBody(name: string, text: string): string | undefined {
+  const declaration = new RegExp(`\\b(?:type|interface)\\s+${name}\\b`).exec(text)
+  if (!declaration) return undefined
+  const open = text.indexOf('{', declaration.index)
+  // An alias to something else (`type Props = PageProps<'/x'>`) has no object body of its own.
+  if (open < 0 || /[;)]/.test(text.slice(declaration.index, open))) return undefined
+  return balanced(text, open, '{', '}')
+}
+
+/** The keys of a destructuring pattern, renames included (`{ params: p }` → `params`). */
+function destructuredKeys(binding: string): Set<string> {
+  const keys = new Set<string>()
+  for (const part of splitTopLevel(balanced(binding, 0, '{', '}'))) {
+    const key = /^\s*(?:\.\.\.)?([\w$]+)/.exec(part)?.[1]
+    if (key) keys.add(key)
+  }
+  return keys
+}
+
+/** Text between `open` at `from` and its matching close, exclusive. */
+function balanced(text: string, from: number, open: string, close: string): string {
+  let depth = 0
+  for (let i = from; i < text.length; i++) {
+    if (text[i] === open) depth++
+    else if (text[i] === close && --depth === 0) return text.slice(from + 1, i)
+  }
+  return ''
+}
+
+function splitTopLevel(list: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < list.length; i++) {
+    const char = list[i]!
+    if (char === '=' && list[i + 1] === '>') i++
+    else if ('({[<'.includes(char)) depth++
+    else if (')}]>'.includes(char)) depth--
+    else if (char === ',' && depth === 0) {
+      parts.push(list.slice(start, i))
+      start = i + 1
+    }
+  }
+  parts.push(list.slice(start))
+  return parts
+}
+
+/** Index of `char` outside any bracket pair, or -1. */
+function topLevelIndex(text: string, char: string): number {
+  let depth = 0
+  for (let i = 0; i < text.length; i++) {
+    const current = text[i]!
+    if ('({[<'.includes(current)) depth++
+    else if (')}]>'.includes(current)) depth--
+    else if (current === char && depth === 0) return i
+  }
+  return -1
+}
+
 function scanSpecialPages(root: string, result: MigrationResult) {
   const found: string[] = []
   for (const base of ['pages', path.join('src', 'pages')]) {

package/src/cli/serve/pipeline.ts

@@ -32,7 +32,7 @@ import {
   malformedUrlResponse,
   trailingSlashRedirect,
 } from '../../routing/href'
-import { withForwardedHeaders } from '../../routing/forwarded'
+import { type PeerAddressSource, withForwardedHeaders } from '../../routing/forwarded'
 import { normalizePathname, parseNavState, selectRouteForRequest } from '../../routing/routes'
 import { runWithCacheScope } from '../../request/cache'
 import { metadataRouteHandlerModule } from '../../routing/metadata-files'
@@ -57,6 +57,7 @@ import {
 } from '../../request/context'
 import { setRequestRuntime } from '../../routing/request-environment'
 import { getRenderSpanExtensions } from '../../render/hooks'
+import { publishEmittedAssets } from '../../css/build'
 import { contentType } from '../../utils/content-type'
 import { stopEsbuildService } from '../../utils/esbuild'
 import { markErrorLogged } from '../../utils/error-log'
@@ -107,6 +108,9 @@ export async function createRequestHandler(
   // so runtime renders observe force-cache / revalidate TTLs / tags exactly
   // like build prerenders. No-op for pure-core apps.
   runInitHooks(config)
+  // Content-hashed asset names, as the build emitted them: a render in THIS
+  // process must link the same files, not the logical `global.css` spelling.
+  publishEmittedAssets(config.outPath, manifest.assetNames)
   // Publish the live routing state the compat request interceptors (action
   // dispatch, rewrites) read; prod loads the route table once.
   setRequestRuntime({ config, routes: manifest.routes, dev: false })
@@ -266,13 +270,13 @@ export async function createRequestHandler(
   // resident esbuild service child (~10+ MB RSS) — it respawns if ever needed.
   stopEsbuildService()
 
-  return function handleRequest(request: Request): Promise<Response> {
+  return function handleRequest(request: Request, server?: PeerAddressSource): Promise<Response> {
     // One work unit spans the whole request; its after-queue flushes once the
     // response fully closes (stream end, redirect, notFound, error, abort).
     return runWithWorkUnit('render', async () => {
       const unit = getWorkUnit()
       try {
-        const raw = await handle(request)
+        const raw = await handle(request, server)
         const finalized = await finalizeResponse(
           raw,
           { method: request.method, url: new URL(request.url), headers: request.headers },
@@ -304,10 +308,10 @@ export async function createRequestHandler(
     })
   }
 
-  async function handle(request: Request): Promise<Response> {
+  async function handle(request: Request, server?: PeerAddressSource): Promise<Response> {
     const badRequest = malformedUrlResponse(request)
     if (badRequest) return badRequest
-    request = withForwardedHeaders(request)
+    request = withForwardedHeaders(request, server)
     const requestedUrl = new URL(request.url)
     // assetPrefix is independent from basePath. Strip a path-style asset
     // prefix first so `/cdn/_next/static/*` remains servable even when the app
@@ -502,6 +506,18 @@ export async function createRequestHandler(
             ? { revalidateSeconds: servedBuilt.metadata.revalidateSeconds }
             : undefined,
         )
+        // A prebuilt DOCUMENT's cache-control belongs to the response finalizer,
+        // which owns the one rule (Next's static / ISR / dynamic values) for
+        // rendered and prebuilt pages alike. maybeBuiltFile's `no-cache` is its
+        // asset default, not a claim; a build-captured header is a claim and stays.
+        if (
+          isHtmlResponse(staticFile) &&
+          !(servedBuilt.metadata?.headers ?? []).some(
+            ([key]) => key.toLowerCase() === 'cache-control',
+          )
+        ) {
+          staticFile.headers.delete('cache-control')
+        }
         if (servedBuilt.metadata) {
           const servedTtl = servedBuilt.metadata.revalidateSeconds
           const expired =
@@ -523,11 +539,14 @@ export async function createRequestHandler(
       }
     }
     if (url.pathname.startsWith('/_next/static/') && !built) {
-      setWorkUnitRoute('static-asset', 'static')
+      setWorkUnitRoute('static-asset')
       return applyProxyResponse(
         new Response('Not Found', {
           status: 404,
-          headers: { 'content-type': 'text/plain' },
+          headers: {
+            'cache-control': 'private, no-cache, no-store, max-age=0, must-revalidate',
+            'content-type': 'text/plain;charset=utf-8',
+          },
         }),
         proxyResponse,
       )
@@ -537,20 +556,7 @@ export async function createRequestHandler(
 
     const matched = selection
     if (!matched) {
-      return applyProxyResponse(
-        compressResponse(
-          await renderGlobalNotFoundResponse({
-            config,
-            url,
-            request: canonicalRequest,
-            staticMetadataFiles: manifest.staticMetadataFiles,
-            staticModuleMetadata: manifest.staticModuleMetadata,
-            staticRouteMetadata: manifest.staticRouteMetadata,
-          }),
-          request,
-        ),
-        proxyResponse,
-      )
+      return applyProxyResponse(await renderNotFound(canonicalRequest), proxyResponse)
     }
     if (matched.route.kind === 'handler') {
       setWorkUnitRoute(
@@ -648,20 +654,7 @@ export async function createRequestHandler(
     // prerendered param set; anything else is a 404. (Prebuilt paths were
     // already served from the static output above.)
     if (!dynamicParamsAllowed(matched.route, matched.params)) {
-      return applyProxyResponse(
-        compressResponse(
-          await renderGlobalNotFoundResponse({
-            config,
-            url,
-            request: canonicalRequest,
-            staticMetadataFiles: manifest.staticMetadataFiles,
-            staticModuleMetadata: manifest.staticModuleMetadata,
-            staticRouteMetadata: manifest.staticRouteMetadata,
-          }),
-          request,
-        ),
-        proxyResponse,
-      )
+      return applyProxyResponse(await renderNotFound(canonicalRequest), proxyResponse)
     }
 
     // force-static routes render with an empty request and no search params
@@ -1324,14 +1317,21 @@ function cachedGzip(key: string, body: Buffer) {
 
 export const immutableCacheControl = 'public, max-age=31536000, immutable'
 
-// Chunk and font filenames are content-hashed, so their bytes can never change under a given URL;
-// entries, css and html keep stable names and must revalidate (no-cache still allows storing, so
-// every revisit is a cheap 304). Compat-registered static-asset prefixes are content-hashed the same
-// way, so they qualify too.
+/**
+ * Everything the build emits under `assets/` (served at `/_next/static/*` in
+ * compat) is immutable, which is the promise Next makes for that whole
+ * namespace. It holds because every one of those names carries a content hash:
+ * esbuild's for chunks and fonts, assetContentHash for the route entries and the
+ * stylesheets (see fingerprintClientEntries / fingerprintAsset), and a build id
+ * for `_next/static/<id>/_*Manifest.js`. An UNHASHED name must never reach here —
+ * the same URL would answer different bytes after a deploy, and every browser
+ * that saw the old ones would keep them for a year.
+ *
+ * Route outputs (prerendered html, handler bodies) live outside both prefixes
+ * and stay revalidating; the public/ tree the app ships is likewise untouched.
+ */
 export function immutableAssetPath(relativePath: string) {
-  if (relativePath.startsWith('assets/chunks/') || relativePath.startsWith('assets/fonts/')) {
-    return true
-  }
+  if (relativePath.startsWith('assets/') || relativePath.startsWith('_next/static/')) return true
   return getAssetExtensions()
     .staticAssetPublicPrefixes()
     .some(prefix => relativePath.startsWith(prefix.replace(/^\/+/, '')))

package/src/cli/start.ts

@@ -15,6 +15,7 @@ import { markErrorLogged } from '../utils/error-log'
 import { isPostpone } from '../render/postpone'
 import { browserHost, ensurePortFree, openBrowser, printServerReady } from './serve/ui'
 import type { BuildManifest } from '../types'
+import type { PeerAddressSource } from '../routing/forwarded'
 
 interface StartOptions {
   root?: string
@@ -22,7 +23,7 @@ interface StartOptions {
   hostname?: string
 }
 
-type RequestHandler = (request: Request) => Promise<Response>
+type RequestHandler = (request: Request, server?: PeerAddressSource) => Promise<Response>
 
 /**
  * The production request handler `pnext start` serves with. Exposed on its own
@@ -47,14 +48,9 @@ export async function start(options: StartOptions = {}) {
   const startedAt = Date.now()
   const port = options.port ?? 3000
   const hostname = options.hostname ?? 'localhost'
-  // Export builds are not served by a production start (Next throws). Standalone builds still serve -
-  // Next only WARNS, pointing at the standalone launcher, and the launcher re-execs this path with
-  // `__NEXT_PRIVATE_STANDALONE_CONFIG` set to suppress that warning. Handle both before binding a
-  // port, matching Next's messages.
+  // Export builds are not served; pnext serves its standalone output directly.
   const config = await guardUnservableOutputMode(options.root)
-  const manifest = JSON.parse(
-    await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
-  ) as BuildManifest
+  const manifest = await readProductionManifest(config)
   await ensurePortFree(port, hostname)
 
   // The pipeline import starts right after listen; a request that beats it
@@ -70,7 +66,8 @@ export async function start(options: StartOptions = {}) {
   const server = Bun.serve({
     hostname,
     port,
-    fetch: request => (handler ? handler(request) : ensureHandler().then(ready => ready(request))),
+    fetch: (request, server) =>
+      handler ? handler(request, server) : ensureHandler().then(ready => ready(request, server)),
   })
 
   printServerReady({
@@ -108,10 +105,20 @@ function installProcessErrorHandlers(): void {
   process.on('uncaughtException', report)
 }
 
-// Next's output-mode handling on start: an export build throws (fatal - it is unservable), while a
-// standalone build only warns and serves on, unless the standalone launcher re-execs with
-// `__NEXT_PRIVATE_STANDALONE_CONFIG` set. pnext mirrors that: load the compat config, read the output
-// mode from the build-compat registry, and reproduce Next's exact messages.
+export async function readProductionManifest(config: ResolvedConfig): Promise<BuildManifest> {
+  try {
+    return JSON.parse(
+      await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
+    ) as BuildManifest
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error("No production build found. Run 'pnext build' first.")
+    }
+    throw error
+  }
+}
+
+// Export output is unservable; pnext production output remains serveable for standalone apps.
 async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig> {
   const config = await loadConfig(root, { serve: true })
   await bootstrapCompat(config)
@@ -123,13 +130,6 @@ async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig>
     )
     process.exit(1)
   }
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (mode === 'standalone' && !process.env.__NEXT_PRIVATE_STANDALONE_CONFIG) {
-    console.warn(
-      '"next start" does not work with "output: standalone" configuration. ' +
-        'Use "node .next/standalone/server.js" instead.',
-    )
-  }
   return config
 }