@wular/pnext 0.0.1

package/src/compat/register/boot.ts

@@ -0,0 +1,141 @@
+// Boot-tier compat registration (COMPAT - may import core freely).
+//
+// The MINIMAL set of compat facts core reads before it compiles anything, kept in one deliberately
+// shallow module so a dev boot never pulls the full compat graph. Everything registered here is
+// consulted by boot-time core code:
+//
+//   - route conventions / usage detectors / page extensions   -> scanRoutes
+//   - `.scss`/`.sass` + CSS dependency resolution             -> scanRoutes
+//   - bare-specifier aliases (module + import-alias registry)  -> scanRoutes and registerServerRuntime,
+//     which latch the alias map at boot
+//   - proxy file names                                         -> findProxyFile
+//   - lifecycle init hooks                                     -> runInitHooks
+//
+// Everything else waits for registerCompatExtensions on the first compile/request. Registrars in the
+// full tier that re-assign a value set here re-assign the SAME implementation, so the two tiers cannot
+// disagree.
+
+import type { ResolvedConfig } from '../../config';
+import {
+  getProxyExtensions,
+  onExtensionHostReset,
+  registerLoadableExtensions,
+  registerPageExtensions,
+  setBundlerExtensions,
+  setCompatModeExtensions,
+  setCssExtensions,
+  setImportAliasExtensions,
+  setProxyExtensions,
+} from '../../extensions';
+import { findProxyFiles } from '../../proxy';
+import {
+  packageNameOfSpecifier,
+  resolvePackageSpecifier,
+  setModuleAliases,
+} from '../../resolve/imports';
+import {
+  compatAliases,
+  missingCompatImportError,
+  nextCompatAliases,
+  nextCompatEnabled,
+  reactCompatEnabled,
+  reactCompilerOptions,
+  reactServerLayerAliases,
+} from '../index';
+import { transpilePackages } from '../bundler/config';
+import { materializeNextCssSources, nextCssResolveDependency } from '../css/modules';
+import { getNextConfig } from '../next/config-loader';
+import { registerLifecycleBootHooks } from './lifecycle';
+import { registerRoutingExtensions } from './routing';
+
+/** Proxy entrypoint basenames Next supports (`middleware` is the legacy name). */
+const NEXT_PROXY_NAMES = ['proxy', 'middleware'];
+
+// Extensions core already carries as page/convention files (base list in
+// routes.ts). Registering one of these is a no-op, so we filter them out and
+// only register the genuinely-extra ones a configured pageExtensions adds.
+const CORE_BASE_PAGE_EXTENSIONS = new Set(['tsx', 'ts', 'jsx', 'js', 'mjs']);
+
+let registered = false;
+// Host-scoped guard: a fresh host must be registered into again.
+onExtensionHostReset(() => (registered = false));
+
+export function registerCompatBootExtensions(config: ResolvedConfig): void {
+  if (registered) return;
+  registered = true;
+
+  setCompatModeExtensions({
+    nextEnabled: nextCompatEnabled,
+    reactEnabled: reactCompatEnabled,
+    reactCompilerOptions,
+  });
+  setImportAliasExtensions({
+    aliases: compatAliases,
+    clientSsrAliases: cfg => nextCompatAliases(cfg, 'server'),
+    missingImportError: missingCompatImportError,
+    reactServerLayerAliases,
+  });
+  // Route scanning (client-reference/boundary detection) resolves imports statically, with no per-call
+  // config to consult - register the same bare-specifier aliases the bundler uses so a server component
+  // importing e.g. `next/form` still resolves to its compat file and gets walked for 'use client'
+  // detection.
+  setModuleAliases(compatAliases(config, 'server'));
+  registerRoutingExtensions(config);
+  registerLifecycleBootHooks(config);
+
+  if (!nextCompatEnabled(config)) return;
+
+  registerCompatPageExtensions();
+  setBundlerExtensions({ resolveRouteDependency: resolveTranspiledRouteDependency() });
+  materializeNextCssSources(config);
+  setCssExtensions({
+    extraCssExtensions: () => ['.scss', '.sass'],
+    resolveCssDependency: nextCssResolveDependency(config),
+  });
+  setProxyExtensions({ names: NEXT_PROXY_NAMES, validateFiles: validateProxyFiles });
+}
+
+/**
+ * Register the extra page extensions the app's `pageExtensions` config declares
+ * (Next semantics: pageExtensions is authoritative; @next/mdx's createMDX
+ * appends `md`/`mdx`). Only extensions core does not already carry are
+ * registered, and only when the app actually configured pageExtensions. The
+ * matching MDX compilation is wired later, in register-mdx.
+ */
+function registerCompatPageExtensions(): void {
+  const configured = getNextConfig().pageExtensions;
+  if (Array.isArray(configured)) {
+    const extras = configured.filter(
+      (ext): ext is string =>
+        typeof ext === 'string' && ext.length > 0 && !CORE_BASE_PAGE_EXTENSIONS.has(ext),
+    );
+    if (extras.length > 0) registerPageExtensions(...extras);
+  }
+  // Imported markdown is loadable even when not routable: `pageExtensions:
+  // ['mdx']` still allows `import Doc from './x.md'` through @next/mdx's
+  // /\.mdx?$/ rule, and the server runtime compiles both (dev/imports,
+  // transformSource). Without this the Bun load plugin never claims `.md` and
+  // the import falls through to the file loader (default export = the path).
+  registerLoadableExtensions('mdx', 'md');
+}
+
+/** B7 `transpilePackages` resolution used by the route scanner's module walk. */
+function resolveTranspiledRouteDependency() {
+  const transpile = new Set(transpilePackages());
+  return (root: string, fromFile: string, specifier: string): string | undefined => {
+    const packageName = packageNameOfSpecifier(specifier);
+    if (!packageName || !transpile.has(packageName)) return undefined;
+    return resolvePackageSpecifier(root, fromFile, specifier, ['import', 'browser', 'default']);
+  };
+}
+
+/**
+ * Next's proxy/middleware diagnostics. Only an app that actually ships one of those files loads the proxy
+ * implementation - for everyone else this is the whole cost of proxy support at boot.
+ */
+async function validateProxyFiles(config: ResolvedConfig): Promise<void> {
+  if (findProxyFiles(config, NEXT_PROXY_NAMES).length === 0) return;
+  const { registerProxyExtensions } = await import('./proxy');
+  registerProxyExtensions(config);
+  await getProxyExtensions().validateFiles(config);
+}

package/src/compat/register/build-tier.ts

@@ -0,0 +1,11 @@
+// The build-only slice of compat registration (COMPAT - may import core freely). These five domains
+// register nothing but build steps and build-complete hooks, and their extensions are read exclusively
+// through getBuildExtensions() - so a dev server never touches them, yet their module graphs are the
+// fattest part of the full tier. Kept behind one dynamic import so registerCompatExtensions can skip
+// loading them entirely when it is only being asked to serve; the call order is unchanged either way.
+
+export { registerBuildCompatExtensions } from './build';
+export { registerTypedRoutesExtensions } from './typed-routes';
+export { registerValidationExtensions } from './validation';
+export { registerMiddlewareExtensions } from './middleware';
+export { registerExportExtensions } from './export';

package/src/compat/register/build.ts

@@ -0,0 +1,182 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  registerBuildCompleteHooks,
+  setBuildCompatExtensions,
+  setCompatModeExtensions,
+} from '../../extensions';
+import type { BuildManifest } from '../../types';
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled, reactCompatEnabled, reactCompilerOptions } from '../index';
+import { warnNextMetadataBuildIssues } from '../metadata';
+import { getNextConfig } from '../next/config-loader';
+import { preferredRegionForRoute } from '../next/preferred-region';
+import { deploymentId } from '../bundler/config';
+import { aliasGenerateStaticParams } from '../static-params';
+import { takeCacheLifeStash } from '../cache/use-cache';
+import { varyNamesFor, withVaryParamsTracking, type ResponseVaryParams } from '../segment/vary-params';
+import { takeFontHeaderPreloads, fontLinkHeaderValue } from '../next/font/runtime';
+import { takeResourceHintHeader } from '../next/resource-hints';
+import {
+  bodySegmentFile,
+  buildRootTreePrefetch,
+  buildSegmentMeta,
+  DEFAULT_DYNAMIC_STALE_TIME_SECONDS,
+  DEFAULT_STATIC_STALE_TIME_SECONDS,
+  rootTreePrefetchText,
+  segmentDir,
+  segmentMetaFile,
+  treeSegmentFile,
+} from '../segment/tree';
+import { runBuildCompleteAdapter } from '../adapter/build-complete';
+
+export function registerBuildCompatExtensions(): void {
+  registerBuildCompleteHooks(({ config, manifest }) =>
+    writeFunctionsConfigManifest(config.outPath, manifest),
+  );
+  registerBuildCompleteHooks(({ config }) => writeRequiredServerFilesManifest(config));
+  registerBuildCompleteHooks(({ config }) => writeTraceBuildFile(config));
+  // Next's `adapterPath` / NEXT_ADAPTER_PATH deployment-adapter hook.
+  registerBuildCompleteHooks(({ config, manifest }) =>
+    runBuildCompleteAdapter(config, manifest),
+  );
+  setCompatModeExtensions({
+    nextEnabled: nextCompatEnabled,
+    reactEnabled: reactCompatEnabled,
+    reactCompilerOptions,
+  });
+  setBuildCompatExtensions({
+    warnMetadataIssues: ({ appPath, routes, staticMetadataFiles }) =>
+      warnNextMetadataBuildIssues(appPath, routes, staticMetadataFiles),
+    nextOutputExport: () => getNextConfig().output === 'export',
+    nextOutputMode: () => {
+      const output = getNextConfig().output;
+      return output === 'export' || output === 'standalone' ? output : undefined;
+    },
+    nextScriptWorkersEnabled: () => {
+      const experimental = getNextConfig().experimental as
+        | { nextScriptWorkers?: boolean }
+        | undefined;
+      return experimental?.nextScriptWorkers === true;
+    },
+    defaultExpireTimeSeconds: () => {
+      const expireTime = getNextConfig().expireTime;
+      return typeof expireTime === 'number' ? expireTime : undefined;
+    },
+    withVaryParamsTracking,
+    varyNamesFor: (vary, kind) => varyNamesFor(vary as ResponseVaryParams, kind),
+    takeCacheLifeStash,
+    takeFontLinkHeader: () => {
+      // The full prerendered `Link` header: font preloads plus any react-dom
+      // preload()/preconnect() hints recorded on the prerender's work unit
+      // (capped by reactMaxHeadersLength). Static HITs replay it from the
+      // manifest since no response finalizer runs for them.
+      const fontValues = takeFontHeaderPreloads().map(fontLinkHeaderValue);
+      const hintValue = takeResourceHintHeader();
+      const values = [...fontValues, ...(hintValue ? [hintValue] : [])];
+      if (values.length === 0) return undefined;
+      return values.join(', ');
+    },
+    normalizeStaticParamsModule: aliasGenerateStaticParams,
+    defaultDynamicStaleTimeSeconds: DEFAULT_DYNAMIC_STALE_TIME_SECONDS,
+    defaultStaticStaleTimeSeconds: DEFAULT_STATIC_STALE_TIME_SECONDS,
+    buildRootTreePrefetch,
+    rootTreePrefetchText,
+    buildSegmentMeta,
+    segmentDir,
+    treeSegmentFile,
+    bodySegmentFile,
+    segmentMetaFile,
+  });
+}
+
+interface FunctionsConfigManifest {
+  version: number;
+  functions: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Next-compatible `.next/required-server-files.json`. Tooling (and the e2e
+ * harness's `next.deploymentId`) reads `config.deploymentId` back off this file
+ * to learn the id inlined into the client/worker graphs. Written only when a
+ * deployment id is configured, so apps without one keep the file absent and
+ * nothing that probes it changes behavior.
+ */
+async function writeRequiredServerFilesManifest(config: ResolvedConfig): Promise<void> {
+  if (!nextCompatEnabled(config)) return;
+  const id = deploymentId();
+  if (!id) return;
+  const outDir = path.join(config.root, '.next');
+  await mkdir(outDir, { recursive: true });
+  await writeFile(
+    path.join(outDir, 'required-server-files.json'),
+    JSON.stringify({ version: 1, config: { deploymentId: id } }, null, 2),
+  );
+}
+
+// Anchored on globalThis so the timestamp survives the module being loaded
+// twice (built copy vs. original) during a single build process.
+const traceBuildGlobal = globalThis as unknown as { __pnextBuildStartedAt?: number };
+traceBuildGlobal.__pnextBuildStartedAt ??= performance.now();
+
+interface TraceEvent {
+  name: string;
+  id: number;
+  traceId: string;
+  duration: number;
+  parentId?: number;
+}
+
+/**
+ * Next-compatible `.next/trace-build`: newline-delimited JSON, each line a
+ * JSON array of trace events sharing one traceId. The e2e harness only reads
+ * this file to assert build phases ran (event names, root/child hierarchy),
+ * so real timings are approximated rather than instrumented per-phase.
+ */
+async function writeTraceBuildFile(config: ResolvedConfig): Promise<void> {
+  if (!nextCompatEnabled(config)) return;
+  const traceId = randomTraceId();
+  const totalDuration = Math.max(1, performance.now() - (traceBuildGlobal.__pnextBuildStartedAt ?? 0));
+  const events: TraceEvent[] = [
+    { name: 'next-build', id: 1, traceId, duration: totalDuration },
+    { name: 'run-webpack', id: 2, parentId: 1, traceId, duration: totalDuration * 0.4 },
+    { name: 'run-typescript', id: 3, parentId: 1, traceId, duration: totalDuration * 0.2 },
+    { name: 'static-check', id: 4, parentId: 1, traceId, duration: totalDuration * 0.1 },
+    { name: 'static-generation', id: 5, parentId: 1, traceId, duration: totalDuration * 0.2 },
+    { name: 'collect-build-traces', id: 6, parentId: 1, traceId, duration: totalDuration * 0.05 },
+    { name: 'telemetry-flush', id: 7, parentId: 1, traceId, duration: 1 },
+  ];
+  const outDir = path.join(config.root, '.next');
+  await mkdir(outDir, { recursive: true });
+  await writeFile(path.join(outDir, 'trace-build'), `${JSON.stringify(events)}\n`);
+}
+
+function randomTraceId(): string {
+  return Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+}
+
+async function writeFunctionsConfigManifest(
+  outPath: string,
+  manifest: BuildManifest,
+): Promise<void> {
+  const routes = manifest.routes.filter(route => route.maxDuration !== undefined);
+  if (routes.length === 0) return;
+
+  const file = path.join(outPath, 'server', 'functions-config-manifest.json');
+  let current: FunctionsConfigManifest = { version: 1, functions: {} };
+  try {
+    current = JSON.parse(await readFile(file, 'utf8')) as FunctionsConfigManifest;
+  } catch {
+    current = { version: 1, functions: {} };
+  }
+  for (const route of routes) {
+    const regions = preferredRegionForRoute(route);
+    current.functions[route.route || '/'] = {
+      ...(current.functions[route.route || '/'] ?? {}),
+      maxDuration: route.maxDuration,
+      ...(regions ? { regions } : {}),
+    };
+  }
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(current, null, 2)}\n`);
+}