mirror of
https://github.com/cloudflare/vinext.git
synced 2026-09-14 19:04:59 +08:00
James Anderson
eca6d3fe83
* feat(router): lazy-load App Router page and route-handler modules
Statically-imported route modules were all evaluated at Worker startup.
For typical pages this is cheap, but routes with expensive module-level
initialization make startup scale linearly and can exceed Cloudflare's
~400ms startup CPU budget. Measured on real Workers: 150 pages with heavy
module-init went from ~414-467ms startup (eager) to ~17ms (lazy); typical
pages are unaffected (~0.01ms/route either way).
The RSC manifest now emits page modules of static routes and all
route-handler modules as `() => import()` thunks instead of eager
`import * as`, so they are code-split out of the entry's top-level
evaluation and loaded on demand for the matched route only.
ensureAppRouteModulesLoaded() hydrates a route's lazy modules onto the
synchronous page/routeHandler fields before any consumer reads them; it is
idempotent and dedups concurrent loads. Hydration is invoked at the central
match point and at every mid-flight route lookup that reads modules before
buildPageElement (server-action redirect/rerender targets, interception and
ISR revalidation source routes).
Dynamic-route pages stay eager because their generateStaticParams is
referenced in the module-level generateStaticParamsMap; making those lazy
needs a prerender-resolver rework and is tracked as follow-up.
* fix(router): retry failed lazy route-module imports instead of caching the rejection
Addresses /bigbonk review feedback on the lazy route-module loader:
- ensureAppRouteModulesLoaded no longer caches a rejected dynamic import().
On failure it clears __loading (leaving __loaded false) and re-throws, so
the current request still sees the error but the next request retries —
matching the eager model's per-isolate retry semantics instead of wedging
the route into a permanent 500 and risking an unhandled rejection.
- Document why the getLazyLoaderVar import() codegen is a CodeQL false
positive (trusted filesystem-scan path, same trust model as the eager
getImportVar import * as).
- Add a rejection-path unit test covering retry-after-failure.
* docs(router): clarify why route handlers can always be lazy-loaded
Reword the getLazyLoaderVar comment per /bigbonk re-review: route handlers
are lazy because they are never sourced into generateStaticParamsMap (which
only reads layouts + page), not because they 'have no generateStaticParams'
(Next.js route handlers can export it for prerendering — a separate gap).
* feat(router): lazy-load all page modules, including dynamic routes
The previous cut kept dynamic-route pages (and anything nested under a
dynamic segment) eager, because their generateStaticParams was referenced
synchronously in the module-level generateStaticParamsMap. That gutted the
benefit for a large class of apps: anything with a dynamic root segment
(i18n `[locale]`, multi-tenant `[org]`) made every route dynamic, so
nothing was lazy — and the heavy `[slug]` page (the prime heavy-module-init
candidate) stayed eager.
Now ALL page modules are lazy. generateStaticParamsMap embeds lazy `{ load }`
page sources instead of `mod.generateStaticParams`, and
createAppPrerenderStaticParamsResolver imports them on demand at prerender
time (already async). It returns the same null "no static params" sentinel
the prerender driver relies on (skip / output:export error), so SSG
behavior is unchanged. Layout generateStaticParams sources stay eager.
The eager set is now just genuinely-shared modules: layouts, templates,
boundaries, intercepts, and global-error.
Verified on real Cloudflare: 150 heavy pages under a dynamic `[locale]`
root went from eager (~450ms startup) to ~22ms, and SSG via the `[locale]`
layout's generateStaticParams still prerenders correctly.
Tests: prerender + prerender-route-params + prerender-endpoints + features +
prod/dev server + interception + actions all green; new
app-prerender-static-params unit tests cover the lazy-source path and null
sentinel; entry-templates updated for all-lazy pages and `{ load }` sources.
* refactor(router): preserve source order in prerender static-params resolver
Per /bigbonk re-review: the resolver partitioned sources into
[...eagerFns, ...lazyFns], which only matched the intended composition order
because the codegen happens to emit layout (eager) sources before the page
(lazy) source. Resolve sources in their original declared order instead —
each source maps to its eager function or its awaited lazy function, then
non-functions are dropped — so composition order no longer depends on the
emitter's append order. Added a unit test with a lazy source ordered before
an eager one.
72 lines
3.1 KiB
TypeScript
72 lines
3.1 KiB
TypeScript
import { describe, expect, it, vi } from "vitest";
|
|
import { createAppPrerenderStaticParamsResolver } from "../packages/vinext/src/server/app-prerender-static-params.js";
|
|
|
|
describe("createAppPrerenderStaticParamsResolver", () => {
|
|
it("returns null when there are no sources at all", () => {
|
|
expect(createAppPrerenderStaticParamsResolver([])).toBeNull();
|
|
// An eager source that is not a function (e.g. `mod?.generateStaticParams`
|
|
// where the module has none) and no lazy sources → still null.
|
|
expect(createAppPrerenderStaticParamsResolver([undefined])).toBeNull();
|
|
});
|
|
|
|
it("resolves an eager generateStaticParams source", async () => {
|
|
const fn = () => [{ id: "a" }, { id: "b" }];
|
|
const resolver = createAppPrerenderStaticParamsResolver([fn]);
|
|
expect(resolver).not.toBeNull();
|
|
await expect(resolver!({ params: {} })).resolves.toEqual([{ id: "a" }, { id: "b" }]);
|
|
});
|
|
|
|
it("loads a lazy page source on demand and reads its generateStaticParams", async () => {
|
|
const load = vi.fn(async () => ({
|
|
generateStaticParams: () => [{ slug: "x" }, { slug: "y" }],
|
|
}));
|
|
const resolver = createAppPrerenderStaticParamsResolver([{ load }]);
|
|
expect(resolver).not.toBeNull();
|
|
// Not loaded until the resolver is actually invoked (prerender time).
|
|
expect(load).not.toHaveBeenCalled();
|
|
|
|
await expect(resolver!({ params: {} })).resolves.toEqual([{ slug: "x" }, { slug: "y" }]);
|
|
expect(load).toHaveBeenCalledTimes(1);
|
|
|
|
// Memoized: a second call does not re-import.
|
|
await resolver!({ params: {} });
|
|
expect(load).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("returns the null sentinel when a lazy page has no generateStaticParams", async () => {
|
|
// A lazy page module with no generateStaticParams export. The resolver is
|
|
// non-null (there is a source) but must yield null so the prerender driver
|
|
// treats the route as having no static params (skip / output:export error).
|
|
const resolver = createAppPrerenderStaticParamsResolver([
|
|
{ load: async () => ({ default: () => null }) },
|
|
]);
|
|
expect(resolver).not.toBeNull();
|
|
await expect(resolver!({ params: {} })).resolves.toBeNull();
|
|
});
|
|
|
|
it("composes an eager layout source with a lazy page source", async () => {
|
|
const layout = () => [{ lang: "en" }, { lang: "fr" }];
|
|
const load = async () => ({ generateStaticParams: () => [{ slug: "post" }] });
|
|
const resolver = createAppPrerenderStaticParamsResolver([layout, { load }]);
|
|
|
|
await expect(resolver!({ params: {} })).resolves.toEqual([
|
|
{ lang: "en", slug: "post" },
|
|
{ lang: "fr", slug: "post" },
|
|
]);
|
|
});
|
|
|
|
it("composes sources in declared order regardless of eager/lazy kind", async () => {
|
|
// Lazy source first, eager second: composition order must follow `sources`
|
|
// order, not be reordered to eager-then-lazy.
|
|
const resolver = createAppPrerenderStaticParamsResolver([
|
|
{ load: async () => ({ generateStaticParams: () => [{ a: "1" }, { a: "2" }] }) },
|
|
() => [{ b: "x" }],
|
|
]);
|
|
|
|
await expect(resolver!({ params: {} })).resolves.toEqual([
|
|
{ a: "1", b: "x" },
|
|
{ a: "2", b: "x" },
|
|
]);
|
|
});
|
|
});
|