Skip to content

perf(pages-router): load Next.js-like client chunks - #4726

Draft
james-elicx wants to merge 1 commit into
mainfrom
perf/pages-router-client-chunks
Draft

james-elicx wants to merge 1 commit into
mainfrom
perf/pages-router-client-chunks

Conversation

@james-elicx

@james-elicx james-elicx commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Pages Router production builds load many more client JS files than Next.js does. On examples/pages-router-complex a desk page loaded 22–23 files, against 5–6 for Next.js webpack and 10 for Turbopack. There were two causes.

_app's imports were split into many chunks. A module that _app and some pages both import (next/link's helpers, next/script, next/dynamic, app components) got a shared chunk of its own, even though every page loads _app. That added up to 8 tiny files on every route. vinext:pages-client-chunks now puts _app's static imports, and what Rolldown finds they use, in one pages-app chunk, short of the framework and vinext chunks. Next.js keeps pages/_app unsplit for the same reason. Nothing is over-fetched, since every page loads _app anyway. _app itself keeps its own chunk, because the client entry imports it and the Pages manifests (CSS order, preloads) look it up by source path. The group starts from _app's direct imports and leaves the rest to Rolldown, so a page-only export of a side-effect-free barrel that _app also imports stays out of the chunk every page loads. An import that statically leads back to _app, to a page or next/dynamic target, or to a module the client entry loads (instrumentation-client's imports, short of the runtime helpers vinext's first group takes) stays in _app's chunk. Rolldown would pull that module into the group too, and in the last case the entry would then load the whole group before _app.

The pages-app chunk holds _app's stylesheets too, in import order. The SSR-manifest backfill now also lists the stylesheets of the chunks a chunk statically imports, ahead of the chunk's own, so a server bundle without the CSS graph (server built before the client) still links _app's CSS.

Small modules shared by different sets of pages each got a tiny common chunk. webpack and Turbopack copy small shared modules into each page instead. With Rolldown 1.2.18+, vinext now turns on codeSplitting.experimentalInlineCommonChunks at 20 kB, Next.js' webpack splitChunks.minSize. Rolldown keeps one instance of each copied module and evaluates it only when an importer needs it, so module evaluation stays the same as in Next.js. Stylesheets are excluded, so a shared CSS module keeps one stylesheet, as in Turbopack (webpack copies it).

I tried merging small shared modules into one chunk and rejected it: a page would then evaluate modules it never imports.

Inlining is skipped on older Rolldown and with options Rolldown rejects in combination with it: strictExecutionOrder: false, non-ESM output, preserveModules, strict entry signatures, onDemandWrapping. It's also skipped when the output already configures it. disableNextLikeChunking: true now turns both changes off. Hybrid App + Pages builds and library builds keep their current chunking, and so does the plain Pages SSR build, which inherits the client output options.

Results

JS files per route on examples/pages-router-complex (production build). Next.js also loads 3 manifest or polyfill files per route on top of these.

Route Next.js webpack Next.js Turbopack main this PR
/, /journal, /workbench 5 10 14–15 7
roster 5 10 22 8
ledger / dispatch / inventory 5–6 10 22–23 10–11
reports / tools / media / search 5–6 10–11 16–17 8

Against webpack, one extra file per route is _app's own chunk. The other extra desk-page files are chunks holding CSS modules, kept on purpose, plus a 1 kB chunk that Rolldown declines to inline: it contains an import() of a module that's also inlined elsewhere.

Inlining makes Rolldown use strict execution order, which wraps each module. That costs about 1.5 kB gzip per route (1.0–2.8 kB) against main, including on routes that inline nothing. Rolldown rejects inlining with strict execution order turned off and with onDemandWrapping.

Fixture

examples/pages-router-complex gains workbench desks that give the client build a varied chunk graph:

  • panels shared by different subsets of pages, and a 36 kB shared table;
  • local vendor packages: a side-effect-free barrel, a CommonJS package, and a package with a CSS module;
  • next/dynamic with and without SSR, React.lazy, and on-demand import();
  • next/image, next/script, next/form and next/navigation.

tests/e2e/pages-router-complex/chunk-scenarios.spec.ts checks each scenario still loads and hydrates. One test checks that a module copied into five page chunks evaluates once across client navigations, and not on a page that doesn't import it.

Tests

  • tests/pages-client-chunks.test.ts builds the new tests/fixtures/pages-client-chunks client and checks several things:

    • _app keeps its own chunk, which imports the one chunk holding a module _app shares with a page, even when a module _app imports imports _app back, and the client entry doesn't load that chunk when _app shares a module with instrumentation-client; an import that uses next/link still joins it;
    • only the barrel export _app uses joins that chunk;
    • a small module three pages share is copied into each page chunk;
    • the shared CSS module stays in one chunk;
    • the SSR build that follows leaves _app's imports alone;
    • disableNextLikeChunking leaves all of this to the bundler.

    It also unit-tests picking _app's imports (including leaving out imports that lead back to _app, to an import() target or to a module the client entry loads, but not ones that only share vinext's first-group helpers with it), the Rolldown version check and the inlining guards.

  • tests/build-optimization.test.ts checks that the SSR-manifest backfill lists the stylesheets of statically imported chunks, deepest first and ahead of the chunk's own.

  • tests/pages-css-order.test.ts now compares cascade positions across the linked stylesheets, since _app's CSS and a component CSS module it shares with a page now share one stylesheet, in import order.

  • chunk-scenarios.spec.ts runs in CI against vp dev and, as the new pages-router-complex-prod project, against a production build.

Performance

Medians of 5 alternating runs, main vs branch:

main branch
vp build, examples/pages-router-complex 2.56 s 2.58 s
vp build, tests/fixtures/pages-basic 1.97 s 2.02 s
vp dev cold start to first / response, examples/pages-router-complex 4.15 s 4.12 s

Dev is unaffected: the plugin only runs in builds. These timings were measured before the review fixes, which only change which modules the pages-app group starts from.

@pkg-pr-new

pkg-pr-new Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@vinext/cloudflare

npm i https://pkg.pr.new/@vinext/cloudflare@4726

create-vinext-app

npm i https://pkg.pr.new/create-vinext-app@4726

@vinext/types

npm i https://pkg.pr.new/@vinext/types@4726

vinext

npm i https://pkg.pr.new/vinext@4726

@cloudflare/workers-response-store

npm i https://pkg.pr.new/@cloudflare/workers-response-store@4726

commit: b371b8e

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Performance benchmarks

Compared b371b8e against base 10ac99c using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 0 regressed · 7 within ±1.5%

Scenario Framework Baseline Current Change
Client bundle size (gzip) vinext 152.4 KB 152.4 KB ⚫ 0.0%
Client entry size (gzip) vinext 140.7 KB 140.7 KB ⚫ 0.0%
Dev server cold start vinext 2.31 s 2.31 s ⚫ +0.0%
Dev server cold start (large Pages Router app) vinext 19.21 s 18.96 s ⚫ -1.3%
Production build time vinext 2.79 s 2.76 s ⚫ -1.2%
RSC entry closure size (gzip) vinext 142.9 KB 142.9 KB ⚫ -0.0%
Server bundle size (gzip) vinext 250.6 KB 250.6 KB ⚫ -0.0%

View detailed results and traces

🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head

@github-actions

Copy link
Copy Markdown
Contributor
Example Preview Production Original
app-router-cloudflare preview production
pages-router-cloudflare preview production
app-router-playground preview production original
realworld-api-rest preview production
nextra-docs-template preview production
benchmarks preview production
hackernews preview production original
response-store-demo preview production
workers-cache preview production
kv preview production
static-assets-cache preview production
static-assets-pages preview production
static-assets-pages-i18n preview production
static-export preview production
web preview production

@james-elicx
james-elicx force-pushed the perf/pages-router-client-chunks branch 4 times, most recently from f1d49e3 to 17c6cc1 Compare November 16, 2026 17:28
Pages Router production builds loaded 14-23 JS files per route on the
pages-router-complex fixture, against 5-6 for Next.js webpack and 10 for
Turbopack. Two causes:

- `_app`'s imports split into many chunks: a module that `_app` and some
  pages both import got a shared chunk of its own, though every page loads
  `_app`. vinext:pages-client-chunks now puts `_app` and its static imports
  in one "pages-app" chunk, as Next.js keeps `pages/_app` unsplit.
- Small modules shared by different sets of pages each got a tiny common
  chunk. With Rolldown 1.2.18+, small common chunks (under 20 kB, Next.js'
  webpack `minSize`) are now copied into their importers through
  `codeSplitting.experimentalInlineCommonChunks`. Each module still
  evaluates once and only when imported, as in webpack and Turbopack.
  Stylesheets keep their own chunk, as Turbopack keeps a shared CSS module
  in one stylesheet.

`disableNextLikeChunking` turns both off. Hybrid App + Pages builds keep
their current chunking.

The pages-router-complex fixture gains workbench desks that produce a
varied client chunk graph (shared panels, a 36 kB shared table, local
vendor packages, next/dynamic, React.lazy, on-demand imports, next/image,
next/script, next/form, next/navigation) with e2e specs, including one that
checks a module copied into several page chunks evaluates once.
@james-elicx
james-elicx force-pushed the perf/pages-router-client-chunks branch from 17c6cc1 to b371b8e Compare November 16, 2026 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant