fix(server-hmr): re-require metadata route handlers per-request in Turbopack dev

Dynamic metadata routes (manifest, robots, sitemap, images) are generated as
virtual wrapper modules with a static top-level import of the user's handler.
When server HMR patches devModuleCache in-place for the user's file, the
wrapper's captured binding still references the old function.

Fix by adding a conditional require() inside the GET handler when running
under Turbopack dev server, mirroring the pattern already used for app-route
handlers. In production and webpack builds the branch is dead code and is
eliminated.

Fixes #91981

Co-Authored-By: Claude <noreply@anthropic.com>

Author: wbinnssmith

crates/next-core/src/next_app/metadata/route.rs

@@ -237,7 +237,14 @@ async fn dynamic_text_route_source(path: FileSystemPath) -> Result<Vc<Box<dyn So
             }}
 
             export async function GET() {{
-              const data = await handler()
+              // In Turbopack dev mode, re-require the user's module on every
+              // request so that server HMR updates are reflected immediately.
+              // The static `handler` import above is kept for the type check
+              // and re-exports; at runtime in dev we bypass it here.
+              const _handler = (process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER)
+                ? require({resource_path}).default
+                : handler
+              const data = await _handler()
               const content = resolveRouteData(data, fileType)
 
               return new NextResponse(content, {{
@@ -293,7 +300,14 @@ async fn dynamic_sitemap_route_with_generate_source(
 
                 const id = await idPromise
                 const hasXmlExtension = id ? id.endsWith('.xml') : false
-                const sitemaps = await generateSitemaps()
+                // In Turbopack dev mode, re-require the user's module on every
+                // request so that server HMR updates are reflected immediately.
+                const _mod = (process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER)
+                  ? require({resource_path})
+                  : null
+                const _handler = _mod ? _mod.default : handler
+                const _generateSitemaps = _mod ? _mod.generateSitemaps : generateSitemaps
+                const sitemaps = await _generateSitemaps()
                 let foundId
                 for (const item of sitemaps) {{
                     if (item?.id == null) {{
@@ -314,7 +328,7 @@ async fn dynamic_sitemap_route_with_generate_source(
                     const hasXmlExtension = id ? id.endsWith('.xml') : false
                     return id && hasXmlExtension ? id.slice(0, -4) : undefined
                 }})
-                const data = await handler({{ id: targetIdPromise }})
+                const data = await _handler({{ id: targetIdPromise }})
                 const content = resolveRouteData(data, fileType)
 
                 return new NextResponse(content, {{
@@ -378,7 +392,12 @@ async fn dynamic_sitemap_route_without_generate_source(
             }}
 
             export async function GET() {{
-                const data = await handler()
+                // In Turbopack dev mode, re-require the user's module on every
+                // request so that server HMR updates are reflected immediately.
+                const _handler = (process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER)
+                  ? require({resource_path}).default
+                  : handler
+                const data = await _handler()
                 const content = resolveRouteData(data, fileType)
 
                 return new NextResponse(content, {{
@@ -443,9 +462,16 @@ async fn dynamic_image_route_with_metadata_source(
                     return rest
                 }})
 
+                // In Turbopack dev mode, re-require the user's module on every
+                // request so that server HMR updates are reflected immediately.
+                const _mod = (process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER)
+                  ? require({resource_path})
+                  : null
+                const _handler = _mod ? _mod.default : handler
+                const _generateImageMetadata = _mod ? _mod.generateImageMetadata : generateImageMetadata
                 const restParams = await restParamsPromise
                 const __metadata_id__ = await idPromise
-                const imageMetadata = await generateImageMetadata({{ params: restParams }})
+                const imageMetadata = await _generateImageMetadata({{ params: restParams }})
                 const id = imageMetadata.find((item) => {{
                     if (item?.id == null) {{
                         throw new Error('id property is required for every item returned from generateImageMetadata')
@@ -460,7 +486,7 @@ async fn dynamic_image_route_with_metadata_source(
                     }})
                 }}
 
-                return handler({{ params: restParamsPromise, id: idPromise }})
+                return _handler({{ params: restParamsPromise, id: idPromise }})
             }}
 
             export * from {resource_path}
@@ -507,7 +533,12 @@ async fn dynamic_image_route_without_metadata_source(
             }}
 
             export async function GET(_, ctx) {{
-                return handler({{ params: ctx.params }})
+                // In Turbopack dev mode, re-require the user's module on every
+                // request so that server HMR updates are reflected immediately.
+                const _handler = (process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER)
+                  ? require({resource_path}).default
+                  : handler
+                return _handler({{ params: ctx.params }})
             }}
 
             export * from {resource_path}

packages/next/src/build/swc/generated-native.d.ts

@@ -153,8 +153,8 @@ export declare function minify(
 export declare function minifySync(input: Buffer, opts: Buffer): TransformOutput
 export interface NapiEndpointConfig {}
 export interface NapiAssetPath {
-  path: string
-  contentHash: string
+  path: RcStr
+  contentHash: RcStr
 }
 export interface NapiWrittenEndpoint {
   type: string
@@ -363,7 +363,7 @@ export interface AppPageNapiRoute {
 }
 export interface NapiRoute {
   /** The router path */
-  pathname: string
+  pathname: RcStr
   /** The relative path from project_path to the route file */
   originalName?: RcStr
   /** The type of route, eg a Page or App */
@@ -522,13 +522,13 @@ export declare function rootTaskDispose(rootTask: {
 export interface NapiIssue {
   severity: string
   stage: string
-  filePath: string
+  filePath: RcStr
   title: any
   description?: any
   detail?: any
   source?: NapiIssueSource
   additionalSources: Array<NapiAdditionalIssueSource>
-  documentationLink: string
+  documentationLink: RcStr
   importTraces: any
   /**
    * Pre-rendered code frame for the issue's source location, if available.
@@ -537,7 +537,7 @@ export interface NapiIssue {
   codeFrame?: string
 }
 export interface NapiAdditionalIssueSource {
-  description: string
+  description: RcStr
   source: NapiIssueSource
   /** Pre-rendered code frame for this additional source location, if available. */
   codeFrame?: string
@@ -551,16 +551,16 @@ export interface NapiIssueSourceRange {
   end: NapiSourcePos
 }
 export interface NapiSource {
-  ident: string
-  filePath: string
+  ident: RcStr
+  filePath: RcStr
 }
 export interface NapiSourcePos {
   line: number
   column: number
 }
 export interface NapiDiagnostic {
-  category: string
-  name: string
+  category: RcStr
+  name: RcStr
   payload: Record<string, string>
 }
 export declare function expandNextJsTemplate(

test/development/app-dir/server-hmr/app/manifest.ts

@@ -0,0 +1,9 @@
+import type { MetadataRoute } from 'next'
+
+export default function manifest(): MetadataRoute.Manifest {
+  return {
+    name: 'My App v1',
+    start_url: '/',
+    display: 'standalone',
+  }
+}

test/development/app-dir/server-hmr/server-hmr.test.ts

@@ -206,4 +206,24 @@ describe('server-hmr', () => {
       }
     )
   })
+
+  describe('metadata route hmr', () => {
+    itTurbopackDev('reflects manifest.ts changes on fetch', async () => {
+      const initial = await next
+        .fetch('/manifest.webmanifest')
+        .then((res) => res.json())
+      expect(initial.name).toBe('My App v1')
+
+      await next.patchFile('app/manifest.ts', (content) =>
+        content.replace('My App v1', 'My App v2')
+      )
+
+      await retry(async () => {
+        const updated = await next
+          .fetch('/manifest.webmanifest')
+          .then((res) => res.json())
+        expect(updated.name).toBe('My App v2')
+      })
+    })
+  })
 })