Commit d6446990 authored by Will Binns-Smith's avatar Will Binns-Smith

Turbopack: enable server HMR for app route handlers (#91466)

App router handlers are already built with the Turbopack runtime, so
they can use server HMR. **We also already get subscription events for
their chunks.** However, unlike app pages which use
`__next_app__.require()` for dynamic devModuleCache lookup, route
handlers capture userland exports statically in AppRouteRouteModule at
construction time. This change makes routes behave a lot like pages,
dynamically loading the user's code when requests are made. This way, we
can freely invalidate and reload it when changes are made without
evicting the entire require cache.

Only `next dev` uses this lazy evaluation, as `next start` continues to
eagerly import route handlers.

This change removes the `isAppPage` restriction from `usesServerHmr`,
extending server HMR coverage to all App Router entries (pages and route
handlers) built with the Node.js runtime.

For route handlers, we also clear the entry chunk from Node.js
`require.cache` on each rebuild so the next `requirePage()` call
re-executes the entry and obtains fresh module exports from
`devModuleCache` (which HMR updates in-place).

Test Plan: Added an additional e2e test, `with-dep`
parent 34de2cac
...@@ -869,7 +869,7 @@ impl ProjectContainer { ...@@ -869,7 +869,7 @@ impl ProjectContainer {
self.project().entrypoints() self.project().entrypoints()
} }
/// See [Project::hmr_chunk_names]. /// See [`Project::hmr_chunk_names`].
#[turbo_tasks::function] #[turbo_tasks::function]
pub fn hmr_chunk_names(self: Vc<Self>, target: HmrTarget) -> Vc<Vec<RcStr>> { pub fn hmr_chunk_names(self: Vc<Self>, target: HmrTarget) -> Vc<Vec<RcStr>> {
self.project().hmr_chunk_names(target) self.project().hmr_chunk_names(target)
...@@ -2318,8 +2318,9 @@ impl Project { ...@@ -2318,8 +2318,9 @@ impl Project {
} }
/// Gets a list of all HMR chunk names that can be subscribed to for the /// Gets a list of all HMR chunk names that can be subscribed to for the
/// specified target. This is only needed for testing purposes and isn't /// specified target. Used by the dev server to set up server-side HMR
/// used in real apps. /// subscriptions for all Node.js App Router entries (pages and route
/// handlers).
#[turbo_tasks::function] #[turbo_tasks::function]
pub async fn hmr_chunk_names(self: Vc<Self>, target: HmrTarget) -> Result<Vc<Vec<RcStr>>> { pub async fn hmr_chunk_names(self: Vc<Self>, target: HmrTarget) -> Result<Vc<Vec<RcStr>>> {
if let Some(map) = self.await?.versioned_content_map { if let Some(map) = self.await?.versioned_content_map {
......
...@@ -2,6 +2,7 @@ import { ...@@ -2,6 +2,7 @@ import {
AppRouteRouteModule, AppRouteRouteModule,
type AppRouteRouteHandlerContext, type AppRouteRouteHandlerContext,
type AppRouteRouteModuleOptions, type AppRouteRouteModuleOptions,
type AppRouteUserlandModule,
} from '../../server/route-modules/app-route/module.compiled' } from '../../server/route-modules/app-route/module.compiled'
import { RouteKind } from '../../server/route-kind' import { RouteKind } from '../../server/route-kind'
import { patchFetch as _patchFetch } from '../../server/lib/patch-fetch' import { patchFetch as _patchFetch } from '../../server/lib/patch-fetch'
...@@ -35,7 +36,6 @@ import { ...@@ -35,7 +36,6 @@ import {
type ResponseCacheEntry, type ResponseCacheEntry,
type ResponseGenerator, type ResponseGenerator,
} from '../../server/response-cache' } from '../../server/response-cache'
import * as userland from 'VAR_USERLAND' import * as userland from 'VAR_USERLAND'
// These are injected by the loader afterwards. This is injected as a variable // These are injected by the loader afterwards. This is injected as a variable
...@@ -59,7 +59,17 @@ const routeModule = new AppRouteRouteModule({ ...@@ -59,7 +59,17 @@ const routeModule = new AppRouteRouteModule({
relativeProjectDir: process.env.__NEXT_RELATIVE_PROJECT_DIR || '', relativeProjectDir: process.env.__NEXT_RELATIVE_PROJECT_DIR || '',
resolvedPagePath: 'VAR_RESOLVED_PAGE_PATH', resolvedPagePath: 'VAR_RESOLVED_PAGE_PATH',
nextConfigOutput, nextConfigOutput,
userland, // The static import is used for initialization (methods, dynamic, etc.).
userland: userland as AppRouteUserlandModule,
// In Turbopack dev mode, also provide a getter that calls require() on every
// request. This re-reads from devModuleCache so HMR updates are picked up,
// and the async wrapper unwraps async-module Promises (ESM-only
// serverExternalPackages) automatically.
...(process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER
? {
getUserland: () => import('VAR_USERLAND'),
}
: {}),
}) })
// Pull out the exports that we need to expose from the module. This should // Pull out the exports that we need to expose from the module. This should
......
...@@ -602,21 +602,16 @@ export async function createHotReloaderTurbopack( ...@@ -602,21 +602,16 @@ export async function createHotReloaderTurbopack(
join(distDir, p) join(distDir, p)
) )
const { type: entryType, page: entryPage } = splitEntryKey(key) const { type: entryType } = splitEntryKey(key)
const isAppPage =
entryType === 'app' &&
currentEntrypoints.app.get(entryPage)?.type === 'app-page'
// Server HMR only applies to app router pages since these use the Turbopack runtime. // Server HMR applies to all App Router entries built with the Turbopack
// Currently, this is only app router pages. // Node.js runtime: both app pages and route handlers. Edge routes,
// // Pages Router pages, and middleware/instrumentation do not use the
// This excludes: // Turbopack Node.js dev runtime and are excluded.
// - Pages Router pages
// - Edge routes
// - Middleware
// - App Router route handlers (route.ts)
const usesServerHmr = const usesServerHmr =
serverFastRefresh && isAppPage && writtenEndpoint.type !== 'edge' serverFastRefresh &&
entryType === 'app' &&
writtenEndpoint.type !== 'edge'
const filesToDelete: string[] = [] const filesToDelete: string[] = []
for (const file of serverPaths) { for (const file of serverPaths) {
...@@ -624,9 +619,9 @@ export async function createHotReloaderTurbopack( ...@@ -624,9 +619,9 @@ export async function createHotReloaderTurbopack(
const relativePath = relative(distDir, file) const relativePath = relative(distDir, file)
if ( if (
// For Pages Router, edge routes, middleware, and manifest files // For Pages Router, edge routes, middleware, and manifest files:
// (e.g., *_client-reference-manifest.js): clear the sharedCache in // clear the sharedCache in evalManifest(), Node.js require.cache,
// evalManifest(), Node.js require.cache, and edge runtime module contexts. // and edge runtime module contexts.
force || force ||
!usesServerHmr || !usesServerHmr ||
!serverHmrSubscriptions?.has(relativePath) !serverHmrSubscriptions?.has(relativePath)
......
...@@ -176,6 +176,12 @@ export interface AppRouteRouteModuleOptions ...@@ -176,6 +176,12 @@ export interface AppRouteRouteModuleOptions
extends RouteModuleOptions<AppRouteRouteDefinition, AppRouteUserlandModule> { extends RouteModuleOptions<AppRouteRouteDefinition, AppRouteUserlandModule> {
readonly resolvedPagePath: string readonly resolvedPagePath: string
readonly nextConfigOutput: NextConfig['output'] readonly nextConfigOutput: NextConfig['output']
/**
* Optional getter that returns the live userland module. When provided (in
* Turbopack dev mode), it is called on every request so that server HMR
* updates are picked up without re-executing the entry chunk.
*/
readonly getUserland?: () => Promise<AppRouteUserlandModule>
} }
/** /**
...@@ -212,32 +218,40 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -212,32 +218,40 @@ export class AppRouteRouteModule extends RouteModule<
public readonly resolvedPagePath: string public readonly resolvedPagePath: string
public readonly nextConfigOutput: NextConfig['output'] | undefined public readonly nextConfigOutput: NextConfig['output'] | undefined
private readonly methods: Record<HTTP_METHOD, AppRouteHandlerFn> private readonly _getUserland?: () => Promise<AppRouteUserlandModule>
private readonly hasNonStaticMethods: boolean private methods: Record<HTTP_METHOD, AppRouteHandlerFn>
private readonly dynamic: AppRouteUserlandModule['dynamic'] private hasNonStaticMethods: boolean
private dynamic: AppRouteUserlandModule['dynamic']
constructor({ constructor({
userland, userland,
getUserland,
definition, definition,
distDir, distDir,
relativeProjectDir, relativeProjectDir,
resolvedPagePath, resolvedPagePath,
nextConfigOutput, nextConfigOutput,
}: AppRouteRouteModuleOptions) { }: AppRouteRouteModuleOptions) {
super({ userland, definition, distDir, relativeProjectDir }) super({
userland: userland!,
definition,
distDir,
relativeProjectDir,
})
this.resolvedPagePath = resolvedPagePath this.resolvedPagePath = resolvedPagePath
this.nextConfigOutput = nextConfigOutput this.nextConfigOutput = nextConfigOutput
this._getUserland = getUserland
// Automatically implement some methods if they aren't implemented by the // Automatically implement some methods if they aren't implemented by the
// userland module. // userland module.
this.methods = autoImplementMethods(userland) this.methods = autoImplementMethods(userland!)
// Get the non-static methods for this route. // Get the non-static methods for this route.
this.hasNonStaticMethods = hasNonStaticMethods(userland) this.hasNonStaticMethods = hasNonStaticMethods(userland!)
// Get the dynamic property from the userland module. // Get the dynamic property from the userland module.
this.dynamic = this.userland.dynamic this.dynamic = userland!.dynamic
if (this.nextConfigOutput === 'export') { if (this.nextConfigOutput === 'export') {
if (this.dynamic === 'force-dynamic') { if (this.dynamic === 'force-dynamic') {
throw new Error( throw new Error(
...@@ -296,8 +310,22 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -296,8 +310,22 @@ export class AppRouteRouteModule extends RouteModule<
// Ensure that the requested method is a valid method (to prevent RCE's). // Ensure that the requested method is a valid method (to prevent RCE's).
if (!isHTTPMethod(method)) return () => new Response(null, { status: 400 }) if (!isHTTPMethod(method)) return () => new Response(null, { status: 400 })
// Return the handler. return autoImplementMethods(this.userland as AppRouteUserlandModule)[method]
return this.methods[method] }
/**
* Like resolve(), but re-fetches the userland module on every call via the
* async getter. Only used in Turbopack dev mode, where server HMR disposes
* modules between requests. The async wrapper also unwraps async-module
* Promises produced by ESM-only serverExternalPackages.
*/
private async resolveWithGetter(
method: string,
getUserland: () => Promise<AppRouteUserlandModule>
): Promise<AppRouteHandlerFn> {
if (!isHTTPMethod(method)) return () => new Response(null, { status: 400 })
const userland = await getUserland()
return autoImplementMethods(userland)[method]
} }
private async do( private async do(
...@@ -692,8 +720,12 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -692,8 +720,12 @@ export class AppRouteRouteModule extends RouteModule<
req: NextRequest, req: NextRequest,
context: AppRouteRouteHandlerContext context: AppRouteRouteHandlerContext
): Promise<Response> { ): Promise<Response> {
// Get the handler function for the given method. // Get the handler function for the given method. In Turbopack dev mode,
const handler = this.resolve(req.method) // use resolveWithGetter() to re-fetch the live userland on every request
// In all other modes, resolve() is synchronous.
const handler = this._getUserland
? await this.resolveWithGetter(req.method, this._getUserland)
: this.resolve(req.method)
// Get the context for the static generation. // Get the context for the static generation.
const staticGenerationContext: WorkStoreContext = { const staticGenerationContext: WorkStoreContext = {
...@@ -738,7 +770,7 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -738,7 +770,7 @@ export class AppRouteRouteModule extends RouteModule<
this.workAsyncStorage.run(workStore, async () => { this.workAsyncStorage.run(workStore, async () => {
// Check to see if we should bail out of static generation based on // Check to see if we should bail out of static generation based on
// having non-static methods. // having non-static methods.
if (this.hasNonStaticMethods) { if (hasNonStaticMethods(this.userland)) {
if (workStore.isStaticGeneration) { if (workStore.isStaticGeneration) {
const err = new DynamicServerError( const err = new DynamicServerError(
'Route is configured with methods that cannot be statically generated.' 'Route is configured with methods that cannot be statically generated.'
...@@ -754,7 +786,8 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -754,7 +786,8 @@ export class AppRouteRouteModule extends RouteModule<
let request = req let request = req
// Update the static generation store based on the dynamic property. // Update the static generation store based on the dynamic property.
switch (this.dynamic) { const { dynamic } = this.userland
switch (dynamic) {
case 'force-dynamic': { case 'force-dynamic': {
// Routes of generated paths should be dynamic // Routes of generated paths should be dynamic
workStore.forceDynamic = true workStore.forceDynamic = true
...@@ -790,7 +823,7 @@ export class AppRouteRouteModule extends RouteModule< ...@@ -790,7 +823,7 @@ export class AppRouteRouteModule extends RouteModule<
request = proxyNextRequest(req, workStore) request = proxyNextRequest(req, workStore)
break break
default: default:
this.dynamic satisfies never dynamic satisfies never
} }
const tracer = getTracer() const tracer = getTracer()
......
export const _hmrTrigger = 0
export const depMessage = 'original message'
export const depEvaluatedAt = Date.now()
import { depMessage, depEvaluatedAt } from './dep'
const routeEvaluatedAt = Date.now()
const routeVersion = 'v1'
export async function GET() {
return Response.json({
depMessage,
depEvaluatedAt,
routeEvaluatedAt,
routeVersion,
})
}
...@@ -178,6 +178,34 @@ describe('server-hmr', () => { ...@@ -178,6 +178,34 @@ describe('server-hmr', () => {
expect(updated).toBe('version: 1') expect(updated).toBe('version: 1')
}) })
}) })
itTurbopackDev(
'does not re-evaluate an unmodified dependency when route changes',
async () => {
const initial = await next
.fetch('/api/with-dep')
.then((res) => res.json())
expect(initial.routeVersion).toBe('v1')
const initialDepEvaluatedAt = initial.depEvaluatedAt
// Change only the route module, not the dependency
await next.patchFile('app/api/with-dep/route.ts', (content) =>
content.replace("'v1'", "'v2'")
)
await retry(async () => {
const updated = await next
.fetch('/api/with-dep')
.then((res) => res.json())
// The route change should be reflected in the response
expect(updated.routeVersion).toBe('v2')
// The unmodified dependency should NOT have been re-evaluated
expect(updated.depEvaluatedAt).toBe(initialDepEvaluatedAt)
})
}
)
}) })
}) })
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment