Skip to content

feat(build): list route rules at the end of the build - #1664

Draft
atinux wants to merge 1 commit into
feat/client-bundle-summaryfrom
feat/build-route-rules
Draft

atinux wants to merge 1 commit into
feat/client-bundle-summaryfrom
feat/build-route-rules

Conversation

@atinux

@atinux atinux commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Written by an AI agent on behalf of @atinux. @atinux has not reviewed it yet.

Stacked on #1663 (client bundle summary), which is stacked on #1662 (quieter server build). Review those first; this PR adds the last two commits: the route rules table, and a fix for the spacing between the summary blocks.

At the end of nuxt build there is no easy way to see which routes are prerendered, cached, client-only, redirected or proxied. Rules come from nuxt.config, from pages (defineRouteRules) and from modules, so the config file alone doesn't tell you.

What changed

  • nuxt build prints a Route rules table (route, rules) after the client bundle summary.
  • The rules are read from the Nitro instance (nitro:init hook) after the build. It is the only place that has page rules and module rules: nuxt.options.routeRules lacks page rules in production builds, and kit.tryUseNitro() returns nothing once the build has finished.
  • Nitro's resolved rules are turned back into short labels: prerender, ssr: false, isr 600s, swr 3600s, cache: false, redirect → /x (307), proxy → url, cors, headers: <names> and middleware. Unknown keys are listed as they are.
  • Works with Nitro 2 and Nitro 3. They resolve rules differently, so both are read:
    • Nitro 3 keeps only cache: { swr, maxAge } for swr.
    • Nitro 3 names the redirect code status, where Nitro 2 uses statusCode.
    • Nitro 3 leaves cors: {} without expanding it into headers.
  • Nuxt's own entries are hidden: /__nuxt_error, the /** ssr: true default, everything under app.buildAssetsDir, the cache header Nitro adds for each publicAssets directory with a maxAge (such as a module's /_og-static-fonts/**), and the _payload.json copies of cached routes. Nuxt renames unnamed page segments to /:_2; they are shown as /* again.
  • Up to 20 routes are listed one per row, sorted. Past 20, routes that share their rules share a row: one row per rule, biggest group first, listing as many routes as fit and then +N more. Redirects are grouped on redirect alone, since each has its own target. Past 20 groups, the rest are counted (+N more rules on M routes).
  • The first column takes at most 40% of the width, and longer routes or rules are cut with …, so the second column stays visible. Rows fit inside clack's gutter.
  • isr: { expiration, allowQuery } shows its expiration (isr 3600s), and prerender: false is left out next to a redirect or proxy.
  • Nothing is printed when the app has no rules of its own.

Videos

Both apps use the same nuxt.config, with 7 route rules and experimental.inlineRouteRules, plus defineRouteRules({ prerender: true }) in pages/blog/[slug].vue. Before is #1663's head (2c6edf6), after is this branch. Recorded with asciinema in a 110×40 terminal and rendered with agg. Pauses are capped at 1.5s, so the clips run faster than the real builds.

Nitro 2 (Nuxt 4.6.2, Nitro 2.13.5)

Before After
nuxt build with Nitro 2 before nuxt build with Nitro 2 after

Nitro 3 (Nuxt 5.0.0-2610281032-c0c2b8f nightly, Nitro 3.0.260903-beta)

Before After
nuxt build with Nitro 3 before nuxt build with Nitro 3 after

Both builds exit 0 and print the same table:

Route rules  8 routes

Route         Rules
/             prerender
/admin/**     ssr: false
/api/**       cors, headers: x-api
/blog/*       prerender
/blog/**      swr 3600s
/old          redirect → /new (307)
/products/**  isr 600s
/proxy/**     proxy → https://example.com/**

The repo playground has no route rules, and its build prints no table.

A large app: nuxt.com

A real nuxt build of nuxt/nuxt.com (15c1ea3) with this branch, in a 110-column terminal: exit 0, 3m 27s. Its build has 382 route rules: 303 redirects (mostly old /docs/2.x paths), 52 ISR, ssr: false, header and proxy rules, and module-added asset rules. Once Nuxt's own rules are hidden, the 352 routes that remain fit in 16 rows grouped by rule:

nuxt build of nuxt.com with route rules grouped by rule

The first version of this PR listed 20 alphabetical routes with no rules visible there. Two Vercel BotID proxy routes of about 75 characters widened the Route column past the terminal, and redirects and asset routes filled the rows.

One blank line between the summary blocks

The second commit fixes the double gap. In a terminal, clack writes a │ spacer row before every message. The client bundle summary and the route rules table each also ended with a newline of their own, so the gap between blocks was two gutter rows. The gap before the client summary was also two rows, from blankLineBefore() plus clack's spacer.

New logBlock() in utils/logger.ts leaves the spacing to clack in a terminal. In redirected output it writes the blank lines itself, starting stdout spacing tracking so a block right after another one does not add a second blank line. Both summary blocks in build.ts now use it. Redirected output is byte-for-byte the same as before around both blocks. test/unit/utils/logger.spec.ts checks both presentations, and its terminal case fails on the old spacing.

Before After
double gap before the fix single gap after the fix

Tests

test/unit/utils/route-rules.spec.ts checks the table against nitro.options.routeRules dumped from real Nitro 2 and Nitro 3 builds and against nuxt.com's rule shapes. It also covers the grouped layout, the cap on groups, and the empty case. The full suite passes (env -u NO_COLOR TERM=xterm-256color pnpm exec vitest run packages: 155 files, 2187 tests), as do eslint and tsc --noEmit.

Details and open questions

  • The videos were recorded before the spacing fix below, so they still show the double gap.
  • The table doesn't say where each rule came from (config, page or module). Nuxt merges them before Nitro sees them, so this would need Nuxt to keep that information.
  • This is a prototype, so it isn't behind a flag. It may need one (or --log-level) for apps with many rules.
  • The timing line wraps at 110 columns; that comes from feat(build): quieter Nitro server build output #1662's phase names, not from this PR.

ELI5

After building, Nuxt now lists every page pattern that has special handling, such as "built ahead of time", "cached for an hour" or "sent to another URL". You can check it matches what you meant without reading through config files and pages.

@atinux
atinux force-pushed the feat/client-bundle-summary branch from 18602f5 to 38d07fe Compare November 8, 2026 08:33
@atinux
atinux force-pushed the feat/build-route-rules branch from c7c87ac to 0b40141 Compare November 8, 2026 08:35
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 38d07fe to 5ab9fa8 Compare November 8, 2026 08:45
@atinux
atinux force-pushed the feat/build-route-rules branch from 0b40141 to 7282bdf Compare November 8, 2026 08:47
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 5ab9fa8 to aba7cd5 Compare November 8, 2026 08:48
@atinux
atinux force-pushed the feat/build-route-rules branch from 7282bdf to 2951767 Compare November 8, 2026 08:50
@atinux
atinux force-pushed the feat/client-bundle-summary branch from aba7cd5 to 71dc0ba Compare November 8, 2026 08:57
@atinux
atinux force-pushed the feat/build-route-rules branch from 2951767 to b3afdc7 Compare November 8, 2026 08:58
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 71dc0ba to 2c6edf6 Compare November 8, 2026 09:14
@atinux
atinux force-pushed the feat/build-route-rules branch 3 times, most recently from ba511a6 to 0e69230 Compare November 8, 2026 09:23
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 2c6edf6 to 893a812 Compare November 9, 2026 22:38
@atinux
atinux force-pushed the feat/build-route-rules branch from 0e69230 to 3738578 Compare November 9, 2026 22:40
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 893a812 to eb95914 Compare November 10, 2026 11:36
@atinux
atinux force-pushed the feat/build-route-rules branch from 3738578 to 128bc02 Compare November 10, 2026 11:38
@atinux
atinux force-pushed the feat/client-bundle-summary branch from eb95914 to a696a61 Compare November 10, 2026 11:42
@atinux
atinux force-pushed the feat/build-route-rules branch from 128bc02 to 8744da0 Compare November 10, 2026 11:44
@atinux
atinux force-pushed the feat/client-bundle-summary branch from a696a61 to b474ee8 Compare November 10, 2026 11:48
@atinux
atinux force-pushed the feat/build-route-rules branch from 2f6be04 to 830cd25 Compare November 10, 2026 11:50
@atinux
atinux force-pushed the feat/client-bundle-summary branch from b474ee8 to 3c02b79 Compare November 12, 2026 10:35
@atinux
atinux force-pushed the feat/build-route-rules branch 2 times, most recently from efa82d6 to 75d9178 Compare November 12, 2026 10:40
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 3c02b79 to 2a97d04 Compare November 12, 2026 10:57
@atinux
atinux force-pushed the feat/build-route-rules branch from 75d9178 to faa61df Compare November 12, 2026 11:00
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 2a97d04 to d23c61a Compare November 12, 2026 11:12
@atinux
atinux force-pushed the feat/build-route-rules branch from faa61df to 9822096 Compare November 12, 2026 11:16
@atinux
atinux force-pushed the feat/client-bundle-summary branch from d23c61a to 3aaf940 Compare November 12, 2026 13:33
@atinux
atinux force-pushed the feat/build-route-rules branch from 9822096 to 66f97a4 Compare November 12, 2026 13:36
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 3aaf940 to 40d4436 Compare November 12, 2026 13:38
@atinux
atinux force-pushed the feat/client-bundle-summary branch from e3eeab1 to 6b7ed3a Compare November 12, 2026 14:26
@atinux
atinux force-pushed the feat/build-route-rules branch from 4e24abb to 0ce7b03 Compare November 12, 2026 14:33
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 6b7ed3a to 08b3d3e Compare November 12, 2026 14:37
@atinux
atinux force-pushed the feat/build-route-rules branch from 0ce7b03 to f2ad3b8 Compare November 12, 2026 14:40
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 08b3d3e to f99d469 Compare November 12, 2026 14:59
@atinux
atinux force-pushed the feat/build-route-rules branch from f2ad3b8 to 0bd801f Compare November 12, 2026 15:02
@atinux
atinux force-pushed the feat/client-bundle-summary branch from f99d469 to bbacef2 Compare November 12, 2026 15:08
@atinux
atinux force-pushed the feat/build-route-rules branch from 0bd801f to 44ff09a Compare November 12, 2026 15:11
@atinux
atinux force-pushed the feat/client-bundle-summary branch from bbacef2 to 02160aa Compare November 12, 2026 15:25
@atinux
atinux force-pushed the feat/build-route-rules branch from 44ff09a to 2311326 Compare November 12, 2026 15:29
@atinux
atinux force-pushed the feat/client-bundle-summary branch 2 times, most recently from d216d21 to bffb11d Compare November 12, 2026 15:38
@atinux
atinux force-pushed the feat/build-route-rules branch 2 times, most recently from 743ec0f to c41c0f4 Compare November 12, 2026 15:42
@atinux
atinux force-pushed the feat/client-bundle-summary branch from bffb11d to 83cbeed Compare November 12, 2026 15:43
@atinux
atinux force-pushed the feat/build-route-rules branch from c41c0f4 to 0286b5c Compare November 12, 2026 15:46
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 83cbeed to 22a8122 Compare November 12, 2026 15:48
@atinux
atinux force-pushed the feat/build-route-rules branch from 0286b5c to cc08408 Compare November 12, 2026 15:51
@atinux
atinux force-pushed the feat/client-bundle-summary branch from 22a8122 to f258062 Compare November 12, 2026 15:55
@atinux
atinux force-pushed the feat/build-route-rules branch from cc08408 to 150f9be Compare November 12, 2026 15:58
@atinux
atinux force-pushed the feat/client-bundle-summary branch from f258062 to a305009 Compare November 12, 2026 16:02
@atinux
atinux force-pushed the feat/build-route-rules branch from 150f9be to b19c417 Compare November 12, 2026 16:06
@atinux
atinux force-pushed the feat/client-bundle-summary branch from a305009 to b0d4a28 Compare November 12, 2026 16:13
@atinux
atinux force-pushed the feat/build-route-rules branch from b19c417 to 987ed48 Compare November 12, 2026 16:16
@atinux
atinux force-pushed the feat/client-bundle-summary branch from b0d4a28 to 2c0c31d Compare November 13, 2026 00:06
@atinux
atinux force-pushed the feat/build-route-rules branch from 987ed48 to 0d00688 Compare November 13, 2026 00:10
@atinux
atinux force-pushed the feat/client-bundle-summary branch 2 times, most recently from 46dc948 to 9f2ae96 Compare November 16, 2026 12:01
@atinux
atinux force-pushed the feat/build-route-rules branch from 0d00688 to edf8438 Compare November 16, 2026 12:05

This branch has not been deployed

No deployments
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