Implement the updated prerender API shape (#84254)

This does not add any validation but it makes the interface for
prerender match out intended API shape when validation is landed

---------

Co-authored-by: Janka Uryga <[email protected]>

Author: gnoff

errors/invalid-prefetch-configuration.mdx

@@ -0,0 +1,31 @@
+---
+title: Invalid Prefetch Configuration
+---
+
+## Why This Message Occurred
+
+You provided an invalid configuration for `export const unstable_prefetch` in a Layout or Page file.
+
+### Example of Correct Usage
+
+#### Static Prefetching
+
+```tsx filename="app/.../layout.tsx"
+export const unstable_prefetch = {
+  mode: 'static',
+}
+```
+
+#### Runtime Prefetching
+
+```tsx filename="app/[slug]/page.tsx"
+export const unstable_prefetch = {
+  mode: 'runtime',
+  samples: [
+    {
+      cookies: [{ name: 'experiment', value: 'A' }],
+      params: { slug: 'example' },
+    },
+  ],
+}
+```

packages/next/src/build/segment-config/app/app-segment-config.ts

@@ -1,6 +1,91 @@
 import { z } from 'next/dist/compiled/zod'
 import { formatZodError } from '../../../shared/lib/zod'
 
+const CookieSchema = z
+  .object({
+    name: z.string(),
+    value: z.string(),
+    httpOnly: z.boolean().optional(),
+    path: z.string().optional(),
+  })
+  .strict()
+
+const RuntimeSampleSchema = z
+  .object({
+    cookies: z.array(CookieSchema).optional(),
+    headers: z.array(z.tuple([z.string(), z.string()])).optional(),
+    params: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    searchParams: z
+      .record(z.union([z.string(), z.array(z.string()), z.undefined()]))
+      .optional(),
+  })
+  .strict()
+
+const StaticPrefetchSchema = z
+  .object({
+    mode: z.literal('static'),
+    from: z.array(z.string()).optional(),
+    expectUnableToVerify: z.boolean().optional(),
+  })
+  .strict()
+
+const RuntimePrefetchSchema = z
+  .object({
+    mode: z.literal('runtime'),
+    samples: z.array(RuntimeSampleSchema).min(1),
+    from: z.array(z.string()).optional(),
+    expectUnableToVerify: z.boolean().optional(),
+  })
+  .strict()
+
+const PrefetchSchema = z.discriminatedUnion('mode', [
+  StaticPrefetchSchema,
+  RuntimePrefetchSchema,
+])
+
+export type Prefetch = StaticPrefetch | RuntimePrefetch
+export type PrefetchForTypeCheckInternal = __GenericPrefetch | Prefetch
+// the __GenericPrefetch type is used to avoid type widening issues with
+// our choice to make exports the medium for programming a Next.js application
+// With exports the type is controlled by the module and all we can do is assert on it
+// from a consumer. However with string literals in objects these are by default typed widely
+// and thus cannot match the discriminated union type. If we figure out a better way we should
+// delete the __GenericPrefetch member.
+interface __GenericPrefetch {
+  mode: string
+  samples?: Array<WideRuntimeSample>
+  from?: string[]
+  expectUnableToVerify?: boolean
+}
+interface StaticPrefetch {
+  mode: 'static'
+  from?: string[]
+  expectUnableToVerify?: boolean
+}
+interface RuntimePrefetch {
+  mode: 'runtime'
+  samples: Array<RuntimeSample>
+  from?: string[]
+  expectUnableToVerify?: boolean
+}
+type WideRuntimeSample = {
+  cookies?: RuntimeSample['cookies']
+  headers?: Array<string[]>
+  params?: RuntimeSample['params']
+  searchParams?: RuntimeSample['searchParams']
+}
+type RuntimeSample = {
+  cookies?: Array<{
+    name: string
+    value: string
+    httpOnly?: boolean
+    path?: string
+  }>
+  headers?: Array<[string, string]>
+  params?: { [key: string]: string | string[] }
+  searchParams?: { [key: string]: string | string[] | undefined }
+}
+
 /**
  * The schema for configuration for a page.
  */
@@ -43,7 +128,7 @@ const AppSegmentConfigSchema = z.object({
    * How this segment should be prefetched.
    * (only applicable when `clientSegmentCache` is enabled)
    */
-  unstable_prefetch: z.enum(['unstable_static', 'unstable_runtime']).optional(),
+  unstable_prefetch: PrefetchSchema.optional(),
 
   /**
    * The preferred region for the page.
@@ -80,11 +165,22 @@ export function parseAppSegmentConfig(
 ): AppSegmentConfig {
   const parsed = AppSegmentConfigSchema.safeParse(data, {
     errorMap: (issue, ctx) => {
-      if (issue.path.length === 1 && issue.path[0] === 'revalidate') {
-        return {
-          message: `Invalid revalidate value ${JSON.stringify(
-            ctx.data
-          )} on "${route}", must be a non-negative number or false`,
+      if (issue.path.length === 1) {
+        switch (issue.path[0]) {
+          case 'revalidate': {
+            return {
+              message: `Invalid revalidate value ${JSON.stringify(
+                ctx.data
+              )} on "${route}", must be a non-negative number or false`,
+            }
+          }
+          case 'unstable_prefetch': {
+            return {
+              // @TODO replace this link with a link to the docs when they are written
+              message: `Invalid unstable_prefetch value ${JSON.stringify(ctx.data)} on "${route}", must be an object with a mode of "static" or "runtime". Read more at https://nextjs.org/docs/messages/invalid-prefetch-configuration`,
+            }
+          }
+          default:
         }
       }
 
@@ -137,7 +233,7 @@ export type AppSegmentConfig = {
    * How this segment should be prefetched.
    * (only applicable when `clientSegmentCache` is enabled)
    */
-  unstable_prefetch?: 'unstable_static' | 'unstable_runtime'
+  unstable_prefetch?: Prefetch
 
   /**
    * The preferred region for the page.

packages/next/src/build/webpack/plugins/next-types-plugin/index.ts

@@ -52,6 +52,8 @@ ${
     : `import type { ResolvingMetadata, ResolvingViewport } from 'next/dist/lib/metadata/types/metadata-interface.js'`
 }
 
+import type { PrefetchForTypeCheckInternal } from 'next/dist/build/segment-config/app/app-segment-config.js'
+
 type TEntry = typeof import('${relativePath}.js')
 
 type SegmentParams<T extends Object = any> = T extends Record<string, any>
@@ -67,7 +69,7 @@ checkFields<Diff<{
   }
   config?: {}
   generateStaticParams?: Function
-  unstable_prefetch?: 'unstable_static' | 'unstable_runtime'
+  unstable_prefetch?: PrefetchForTypeCheckInternal
   revalidate?: RevalidateRange<TEntry> | false
   dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static'
   dynamicParams?: boolean

packages/next/src/server/app-render/create-component-tree.tsx

@@ -221,7 +221,7 @@ async function createComponentTreeInternal(
     ? (layoutOrPageMod as AppSegmentConfig).unstable_prefetch
     : undefined
   /** Whether this segment should use a runtime prefetch instead of a static prefetch. */
-  const hasRuntimePrefetch = prefetchConfig === 'unstable_runtime'
+  const hasRuntimePrefetch = prefetchConfig?.mode === 'runtime'
 
   const [Forbidden, forbiddenStyles] =
     authInterrupts && forbidden

packages/next/src/server/typescript/rules/config.ts

@@ -159,12 +159,12 @@ const API_DOCS: Record<
   unstable_prefetch: {
     description: `Specifies the default prefetching behavior for this segment. This configuration is currently under development and will change.`,
     link: '(docs coming soon)',
-    options: {
-      '"unstable_static"':
-        'Only static and cached parts of the page will be prefetched. (default)',
-      '"unstable_runtime"':
-        'Parts of the page that use route params, search params, or cookies will also be prefetched.',
-    } satisfies DocsOptionsObject<FullAppSegmentConfig['unstable_prefetch']>,
+    type: 'object',
+    // TODO: ideally, we'd validate the config object somehow, but this is difficult to do
+    // with the way this plugin is currently structured.
+    // For now, since we don't provide an `options` here, we won't do any validation in
+    // `getSemanticDiagnosticsForExportVariableStatement` below, and only provide hover a tooltip + autocomplete.
+    insertText: 'unstable_prefetch = { mode: "static" };',
   },
 }
 

test/e2e/app-dir/segment-cache/prefetch-layout-sharing/app/segment-config/runtime-prefetchable/configured-as-runtime/page.tsx

@@ -1,7 +1,10 @@
 import { cookies } from 'next/headers'
 import { Suspense } from 'react'
 
-export const unstable_prefetch = 'unstable_runtime'
+export const unstable_prefetch = {
+  mode: 'runtime',
+  samples: [{ cookies: [] }],
+}
 
 export default function Page() {
   return (

test/e2e/app-dir/segment-cache/prefetch-layout-sharing/app/segment-config/runtime-prefetchable/configured-as-static/page.tsx

@@ -4,8 +4,9 @@ import { Suspense } from 'react'
 
 // Technically, no `export const unstable_prefetch = ...` is needed, because we default to static,
 // this is just to make sure that we excercise the codepaths for it
-export const unstable_prefetch = 'unstable_static'
-
+export const unstable_prefetch = {
+  mode: 'static',
+}
 export default function Page() {
   return (
     <main>

test/e2e/app-dir/segment-cache/prefetch-layout-sharing/app/segment-config/runtime-prefetchable/layout.tsx

@@ -2,8 +2,10 @@ import { cookies } from 'next/headers'
 import { Suspense } from 'react'
 import { DebugRenderKind } from '../../shared'
 
-export const unstable_prefetch = 'unstable_runtime'
-
+export const unstable_prefetch = {
+  mode: 'runtime',
+  samples: [{ cookies: [] }],
+}
 export default async function Layout({ children }) {
   return (
     <main>

test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/fully-static/page.tsx

@@ -3,7 +3,10 @@
 // but it's useful to exercise this codepath.
 // In the future, this test can be used to check whether we correctly
 // *skip* a runtime prefetch if a page was prerendered as static.
-export const unstable_prefetch = 'unstable_runtime'
+export const unstable_prefetch = {
+  mode: 'runtime',
+  samples: [{ cookies: [] }],
+}
 
 export default async function Page() {
   return (

test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/in-page/cookies-only/page.tsx

@@ -2,7 +2,10 @@ import { cookies } from 'next/headers'
 import { Suspense } from 'react'
 import { cachedDelay, DebugRenderKind } from '../../../shared'
 
-export const unstable_prefetch = 'unstable_runtime'
+export const unstable_prefetch = {
+  mode: 'runtime',
+  samples: [{ cookies: [{ name: 'testCookie', value: 'testValue' }] }],
+}
 
 export default async function Page() {
   return (