Unverified Commit fea75474 authored by Will Binns-Smith's avatar Will Binns-Smith Committed by GitHub

Route Handlers: Fix devRequestTimingInternalsEnd and Turbopack server HMR (#92271)

### What?

Fixes issues with `AppRouteRouteModule` that interact with
`devRequestTiming` and Turbopack server HMR.

1. **Incorrect `devRequestTimingInternalsEnd` attribution**: The
app-route template previously statically imported userland (`import * as
userland from 'VAR_USERLAND'`), meaning module load time was included in
the framework's startup overhead. The `devRequestTimingInternalsEnd`
timestamp is now set immediately before `routeModule.handle()` is
called, and userland is loaded lazily on the first request so the timing
correctly captures the framework→application boundary.

2. **Stale route handlers after Turbopack server HMR**: After a
Turbopack server HMR update, `devModuleCache` is updated with a fresh
route module, but the entry chunk remains in Node.js `require.cache`.
The lazy `_userlandFactory` only runs once and would cache the old
module reference — so route handler changes were not reflected after
HMR. This restores a synchronous per-request `getUserland` getter that
calls `require('VAR_USERLAND')` on every request. Since `require()` is a
synchronous `devModuleCache` lookup, it has negligible overhead and
doesn't add async time that would be incorrectly attributed to
`application-code`.

3. **Route handlers with top-level await**: `require()` returns a
Promise for modules that use top-level await. The module now accepts a
lazy factory for `userland` and handles this case via
`ensureUserland()`, which is called before the first request is handled.

4. **`output: export` route validation**: With the lazy factory,
validation errors (e.g. `dynamic = "force-dynamic"` on an exported
route) were deferred to request time, returning a 500 instead of
surfacing as a Redbox in dev. The constructor now eagerly calls the
factory for `output: export` routes so `_initFromUserland()` throws at
module-load time — preserving the Redbox error.

5. **`node:stream` in edge bundles** (CI fix): `render-result.ts` was
missing a `NEXT_RUNTIME === 'edge'` compile-time guard around
`require('node:stream')` / `__non_webpack_require__('node:stream')`,
which prevented webpack from DCE-ing those branches in edge builds.
Vercel's deploy adapter rejects edge functions that reference
`node:stream`. The guard is now restored to match the canary pattern.

### Why?

#91466 enabled server HMR for app route handlers and introduced
`getUserland: () => import('VAR_USERLAND')` to pick up HMR updates on
each request. However, the async `import()` adds latency incorrectly
attributed to application-code time in `devRequestTiming`. This PR
replaces `import()` with synchronous `require()` and also lazily loads
userland on the first request for accurate
`devRequestTimingInternalsEnd` placement.

### How?

- **Template** (`app-route.ts`): Replaces the static `import * as
userland` with a lazy `() => require('VAR_USERLAND')` factory. In
Turbopack dev mode, also provides `getUserland: () =>
require('VAR_USERLAND')` — a synchronous getter called on every request
to pick up server HMR updates.

- **Module** (`module.ts`):
  - Accepts `userland` as either a direct module or a lazy factory.
- For `output: export` routes, calls the factory eagerly in the
constructor so `_initFromUserland()` validation errors throw at
module-load time (Redbox) rather than at request time (500).
- For async modules (top-level await), stores the pending Promise in
`_pendingUserland` so `ensureUserland()` can await it before the first
request.
- Accepts optional synchronous `getUserland` for per-request live
userland access (Turbopack dev HMR).
- `handle()` calls `_getUserland?.()` at request start; if set, uses the
result for handler resolution, `fetchCache`, `hasNonStaticMethods`, and
`dynamic` — ensuring HMR changes to all exported values are immediately
reflected.
- Extracts `_initFromUserland()` helper to deduplicate initialization
between lazy and eager paths.

- **Route module base** (`route-module.ts`): Makes `isDev` public for
template access.

- **Test** (`app-custom-routes.test.ts` + fixture): Adds an integration
test for route handlers that use top-level await, ensuring the handler
is correctly resolved even when `require()` returns a Promise.

- **`render-result.ts`**: Restores the `if (process.env.NEXT_RUNTIME ===
'edge') { throw }` guard matching canary, so `node:stream` is DCE'd from
edge builds.

Fixes #91318

---------
Co-authored-by: 's avatarWill Binns-Smith <wbinnssmith@users.noreply.github.com>
Co-authored-by: 's avatarClaude <noreply@anthropic.com>
parent a43cf0c2
...@@ -2,7 +2,6 @@ import { ...@@ -2,7 +2,6 @@ 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'
...@@ -36,7 +35,6 @@ import { ...@@ -36,7 +35,6 @@ import {
type ResponseCacheEntry, type ResponseCacheEntry,
type ResponseGenerator, type ResponseGenerator,
} from '../../server/response-cache' } from '../../server/response-cache'
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
// instead of a replacement because this could also be `undefined` instead of // instead of a replacement because this could also be `undefined` instead of
...@@ -59,15 +57,24 @@ const routeModule = new AppRouteRouteModule({ ...@@ -59,15 +57,24 @@ 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,
// The static import is used for initialization (methods, dynamic, etc.). // Always use a lazy require factory so that:
userland: userland as AppRouteUserlandModule, // - In dev: devRequestTimingInternalsEnd is set before userland executes,
// In Turbopack dev mode, also provide a getter that calls require() on every // correctly attributing module load time to application-code rather than
// request. This re-reads from devModuleCache so HMR updates are picked up, // framework internals.
// and the async wrapper unwraps async-module Promises (ESM-only // - In all modes: async modules (route files with top-level await) are
// serverExternalPackages) automatically. // handled correctly — require() returns a Promise for such modules, which
// ensureUserland() awaits before the first request is handled. Eagerly
// calling require() would pass that Promise directly to the constructor
// and break _initFromUserland().
userland: () => require('VAR_USERLAND') as typeof import('VAR_USERLAND'),
// In Turbopack dev mode, also provide a synchronous per-request getter so
// server HMR updates are picked up without re-executing the entry chunk.
// Using require() (synchronous) avoids adding async overhead that would be
// incorrectly attributed to application-code time in devRequestTiming.
...(process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER ...(process.env.TURBOPACK && process.env.__NEXT_DEV_SERVER
? { ? {
getUserland: () => import('VAR_USERLAND'), getUserland: () =>
require('VAR_USERLAND') as typeof import('VAR_USERLAND'),
} }
: {}), : {}),
}) })
......
...@@ -88,6 +88,11 @@ export async function exportAppRoute( ...@@ -88,6 +88,11 @@ export async function exportAppRoute(
} }
try { try {
// Ensure the userland module is fully loaded before accessing it. This is
// required for route files that use top-level await: require() returns a
// Promise for async modules, so module.userland would be undefined until
// the Promise resolves.
await module.ensureUserland()
const userland = module.userland const userland = module.userland
// we don't bail from the static optimization for // we don't bail from the static optimization for
// metadata routes, since it's app-route we can always append /route suffix. // metadata routes, since it's app-route we can always append /route suffix.
......
...@@ -108,10 +108,13 @@ export abstract class RouteModule< ...@@ -108,10 +108,13 @@ export abstract class RouteModule<
> { > {
/** /**
* The userland module. This is the module that is exported from the user's * The userland module. This is the module that is exported from the user's
* code. This is marked as readonly to ensure that the module is not mutated * code. Exposed as a getter so subclasses can override with lazy loading.
* because the module (when compiled) only provides getters.
*/ */
public readonly userland: Readonly<U> protected _userland: Readonly<U>
get userland(): Readonly<U> {
return this._userland
}
/** /**
* The definition of the route. * The definition of the route.
...@@ -135,7 +138,7 @@ export abstract class RouteModule< ...@@ -135,7 +138,7 @@ export abstract class RouteModule<
distDir, distDir,
relativeProjectDir, relativeProjectDir,
}: RouteModuleOptions<D, U>) { }: RouteModuleOptions<D, U>) {
this.userland = userland this._userland = userland
this.definition = definition this.definition = definition
this.isDev = !!process.env.__NEXT_DEV_SERVER this.isDev = !!process.env.__NEXT_DEV_SERVER
this.distDir = distDir this.distDir = distDir
......
...@@ -709,4 +709,12 @@ describe('app-custom-routes', () => { ...@@ -709,4 +709,12 @@ describe('app-custom-routes', () => {
expect(cliOutput).not.toContain('Attempted import error') expect(cliOutput).not.toContain('Attempted import error')
}) })
}) })
describe('top-level await', () => {
it('handles route handlers that use top-level await', async () => {
const res = await next.fetch(basePath + '/top-level-await')
expect(res.status).toBe(200)
expect(await res.text()).toBe('hello from top-level await')
})
})
}) })
// This route uses a top-level await to simulate an async module (e.g. a route
// that fetches config or initializes a DB connection at module load time).
// require() returns a Promise for such modules, so the route module must not
// eagerly call _initFromUserland() before the Promise resolves.
const message = await Promise.resolve('hello from top-level await')
export async function GET() {
return new Response(message)
}
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