|
| 1 | +# Vite Dev Middleware — Request Routing |
| 2 | + |
| 3 | +> Scope: the request-routing logic in `src/build/vite/dev.ts` — the two |
| 4 | +> `server.middlewares.use(...)` registrations (`nitroDevMiddlewarePre` and the |
| 5 | +> catch-all `nitroDevMiddleware`): why the current design looks the way it does. |
| 6 | +
|
| 7 | +## 1. Where it lives & how it is wired |
| 8 | + |
| 9 | +- Logic: `src/build/vite/dev.ts` → `configureViteDevServer(ctx, server)`. |
| 10 | +- Entry: `src/build/vite/plugin.ts:266` — the plugin's `configureServer` hook |
| 11 | + `return`s the result of `configureViteDevServer`. |
| 12 | + |
| 13 | +Vite's `configureServer` contract: middleware registered **synchronously** |
| 14 | +inside the hook runs **before** Vite's internal middlewares; a function |
| 15 | +**returned** from the hook runs **after** them (the "post" hook). Nitro uses |
| 16 | +both ends: |
| 17 | + |
| 18 | +| Registration | Site | Runs | Role | |
| 19 | +|---|---|---|---| |
| 20 | +| `nitroDevMiddlewarePre` (`function` form) | `dev.ts:281` | **before** Vite static/transform | Classifier. Route explicit-Nitro + definite navigations to Nitro immediately; let definite assets fall through to Vite, marking them `_nitroHandled` (transparent catch-all) or `_nitroAssetCheck` (opaque catch-all / no match). | |
| 21 | +| `nitroDevMiddleware` | `dev.ts:374`, inside the returned `() => { ... }` | **after** Vite static/transform | Catch-all fallback. Wraps req as web `Request`, tries `ctx.devApp.fetch` then `nitroEnv.dispatchFetch`, honoring `baseURL`; inspects the response for `_nitroAssetCheck` requests. Skipped for `_nitroHandled`. | |
| 22 | + |
| 23 | +**Why two, and why pre?** Without the pre-pass, Vite's static/transform |
| 24 | +middleware serves files from the project root and would answer server routes |
| 25 | +before Nitro sees them (see upstream **vitejs/vite#20866**, which made Vite |
| 26 | +consult `sec-fetch-dest` to let document requests fall through — the same |
| 27 | +header Nitro's classifier leans on). |
| 28 | + |
| 29 | +Facts about Vite's side (verified against vite@8.1.4): Nitro forces |
| 30 | +`appType: "custom"` (`plugin.ts:199`), so Vite registers none of |
| 31 | +`htmlFallback`/`indexHtml`/`notFound` middlewares, and **every plain miss |
| 32 | +`next()`s** (sirv and transformMiddleware never self-emit a 404 for a missing |
| 33 | +file/module). The only terminal 404 is connect's `finalhandler`, which sits |
| 34 | +**after** the Nitro post-hook. So Vite genuinely hands off every request it |
| 35 | +cannot serve — the post catch-all is the last handler before `finalhandler`. |
| 36 | + |
| 37 | +## 2. Classification |
| 38 | + |
| 39 | +`nitro.routing.routes` in an SSR app **always** contains a catch-all `/**`, so |
| 40 | +"does a Nitro route match?" is nearly always *yes*. The design distinguishes: |
| 41 | + |
| 42 | +- **Explicit route** — `route` set, `!== "/**"`, not `startsWith("/**:")` (a |
| 43 | + prefixed splat like `/api/photos/**` is explicit). Deterministic → **always |
| 44 | + Nitro**, no heuristic may override (#4108, #4241, #4252, #4270). |
| 45 | +- **Explicit public asset** — a public-asset dir under a non-root `baseURL` |
| 46 | + with `fallthrough: false` owns its subtree → Nitro, like an explicit route. |
| 47 | +- **Transparent catch-all** — a *user route file* at root level |
| 48 | + (`routes/[...].ts` → `/**`, `routes/[...slug].ts` → `/**:slug`). Nitro sees |
| 49 | + everything it can handle, so Vite stays the definitive asset handler: an |
| 50 | + asset-tagged request is marked `_nitroHandled` and a Vite miss must **not** |
| 51 | + fall back into it (#4234/#4266). |
| 52 | +- **Opaque catch-all** — the SSR renderer `/**` or a custom `serverEntry` `/**` |
| 53 | + (both registered in `routing.ts` with identifiable `handler` paths). Their |
| 54 | + *real* routes are invisible to the host (`server.ts` H3 app routes, framework |
| 55 | + routers like TanStack Start), so an asset-tagged miss from Vite must still be |
| 56 | + **dispatched** — marked `_nitroAssetCheck`, decided by response inspection. |
| 57 | +- **None** — no match. Extensionless → page navigation → Nitro; asset-tagged → |
| 58 | + same as opaque (`_nitroAssetCheck`, dispatch after Vite). |
| 59 | + |
| 60 | +## 3. The asset heuristic (catch-all / none case only) |
| 61 | + |
| 62 | +Set `Vary: sec-fetch-dest, accept`, then: |
| 63 | + |
| 64 | +- **`Sec-Fetch-Dest` present & concrete** (not `empty`): `document`/`iframe`/ |
| 65 | + `frame` = navigation → Nitro; anything else (`image`, `video`, `style`, …) = |
| 66 | + asset. |
| 67 | +- **Absent or `empty`**: fall back to extension — `ASSET_EXT_RE.test(ext)` |
| 68 | + **and** no `text/html` in `Accept` ⇒ asset. (`empty` = fetch/XHR is ambiguous: |
| 69 | + it tags both API calls and `fetch()`ed assets.) |
| 70 | +- Non-asset + (matched or extensionless) → Nitro immediately (pre-Vite). |
| 71 | + |
| 72 | +Two regexes to keep intact: |
| 73 | +- `ASSET_EXT_RE` (`dev.ts:24`) — narrow on purpose, so dotted Nitro params like |
| 74 | + `/foo.bar.1` still reach Nitro (#4108). |
| 75 | +- Extension is extracted from the path only (query/hash stripped) so |
| 76 | + `?file=bar.png` does not misclassify. |
| 77 | + |
| 78 | +## 4. Response inspection (`_nitroAssetCheck`) |
| 79 | + |
| 80 | +An asset-tagged request that only an opaque catch-all could handle cannot be |
| 81 | +classified **a priori** — `/image.png` may be a real custom-entry route (#4252) |
| 82 | +or a genuinely missing asset that a naive SSR `/**` would render as a 200 page |
| 83 | +(#4234). It *can* be classified from the **response**: after Vite declines and |
| 84 | +the post catch-all dispatches to Nitro, a 2xx with a page-ish content-type |
| 85 | +(`PAGE_CONTENT_RE`, `dev.ts:33`: `text/html` | `application/json`) means the |
| 86 | +catch-all swallowed a missing asset → the response is discarded via `next()` |
| 87 | +(connect `finalhandler` 404, same as before). Anything else — real asset types, |
| 88 | +`text/plain`, no content-type, non-2xx (framework 404 pages, redirects) — |
| 89 | +passes through verbatim. |
| 90 | + |
| 91 | +Deny-list rationale (all verified empirically): |
| 92 | + |
| 93 | +- `application/json` is included because a naive SSR entry can swallow with |
| 94 | + JSON, not just HTML (the `app-fixture` entry does exactly that). |
| 95 | +- `text/plain` is excluded because a bare string returned from an h3 handler |
| 96 | + has **no** content-type at the h3 layer but crosses the worker bridge as a |
| 97 | + `Response` with the fetch-spec default `text/plain;charset=UTF-8` — it must |
| 98 | + pass through (custom-entry handlers returning strings). |
| 99 | +- Transparent (user-file) catch-alls can **not** use inspection instead of the |
| 100 | + divert: their string 200s arrive with no distinguishing content-type. |
| 101 | + |
| 102 | +This keeps everything zero-config, host-side only (no runtime/bundle change, |
| 103 | +no production behavior change). Known leftover: **production** SSR still |
| 104 | +renders 200 HTML for missing-asset URLs — pre-existing behavior; changing it |
| 105 | +is a separate, deliberate breaking-change discussion. |
| 106 | + |
| 107 | +## 5. Issue / PR lineage (chronological) |
| 108 | + |
| 109 | +- **#3649** first crude "has extension ⇒ Vite" rule; **#3804/#3805/#3817** |
| 110 | + middleware improvements, mounted-path skip, internal-prefix skip (survives as |
| 111 | + the `^\/(?:__|@)` guard); **#4098** `sec-websocket-protocol` to tell Vite HMR |
| 112 | + sockets from Nitro websockets (the `upgrade` handler). |
| 113 | +- **#4108** baseURL-aware matching for dotted Nitro routes |
| 114 | + (TanStack/router#6903). |
| 115 | +- **#4234** non-loopback plain-HTTP origins omit `Sec-Fetch-*` → splat swallowed |
| 116 | + `<script src>` loads. Fixed by **#4238**: `Accept` + `ASSET_EXT_RE` fallback + |
| 117 | + the `_nitroHandled` marker. |
| 118 | +- **#4241** #4238 over-eager: `sec-fetch-dest: image` on a real route |
| 119 | + (`/api/image`) sent to Vite → 404. Fixed by `7d49dcae` + `08f2ec69` |
| 120 | + (query-string stripped before extension matching). |
| 121 | +- **#4252 / #4270** even explicit routes lost when the URL had an asset |
| 122 | + extension. Fixed by **#4272** (`5b7e152b`): explicit vs catch-all vs none |
| 123 | + classification — **an explicit route is a deterministic win no heuristic can |
| 124 | + touch**. |
| 125 | +- `7765bcb7` added `isExplicitPublicAsset`. |
| 126 | +- **#4252 follow-ups** (katywings, jantimon/TanStack/router#7403): routes the |
| 127 | + classifier cannot see — a custom `server.ts` H3 app serving `/image.png`, or |
| 128 | + an SSR framework serving assets — were pre-empted by `_nitroHandled` and |
| 129 | + could never run. Fixed by the opaque-catch-all + response-inspection design |
| 130 | + above (§2, §4): the pre-emption now applies only to transparent user-file |
| 131 | + catch-alls, and opaque dispatches are judged by their response content-type. |
| 132 | + |
| 133 | +## 6. Runtime dispatch flow |
| 134 | + |
| 135 | +The catch-all `nitroDevMiddleware` dispatches in two stages: |
| 136 | + |
| 137 | +1. **`ctx.devApp.fetch(req)`** — `NitroDevApp` (`src/dev/app.ts`), host-side: |
| 138 | + `devHandlers`, `/_vfs/**`, `/_nitro/tasks`, public asset dirs, `devProxy`. |
| 139 | + No catch-all → a 404 means "not mine, hand off"; any non-404 is returned |
| 140 | + directly (never inspected — deterministic host serves are authoritative). |
| 141 | +2. **`nitroEnv.dispatchFetch(req)`** → env-runner → worker → `nitroApp.fetch` → |
| 142 | + full route table, middleware, catch-alls. |
| 143 | + |
| 144 | +Catch-all registration (`src/routing.ts`): a custom `serverEntry` is pushed as |
| 145 | +`/**` with `handler = nitro.options.serverEntry.handler`; the SSR renderer as |
| 146 | +`/**` with `handler = nitro.options.renderer.handler` (set by `plugin.ts` |
| 147 | +`configResolved` to `internal/vite/ssr-renderer` when an `ssr` service exists). |
| 148 | +These handler paths are how the pre-pass identifies opaque catch-alls. |
| 149 | + |
| 150 | +## 7. Test coverage map |
| 151 | + |
| 152 | +All under `test/vite/`; run via `test:rollup` and `test:rolldown`. Each starts |
| 153 | +a real Vite dev server and `fetch()`es with hand-set headers. |
| 154 | + |
| 155 | +- `app.test.ts` (`app-fixture/`) — SSR `/**` path. #4234 swallow contracts |
| 156 | + (missing `.css`/`.js` under `style`/absent/`empty` dests must not 200 — the |
| 157 | + fixture entry swallows with **JSON**, keeping the deny-list honest), #4252 |
| 158 | + deliberate asset serve (`/dynamic-asset.png` → `image/png` passes |
| 159 | + inspection), `HTTPError` propagation, navigations, storage/config sharing. |
| 160 | +- `server-entry.test.ts` (`server-entry-fixture/`) — #4252 custom `server.ts` |
| 161 | + H3 app: asset-extensioned routes reachable under `image`/absent/`script` |
| 162 | + dests (including a no-content-type string return), missing-asset 404 |
| 163 | + contract, navigation. |
| 164 | +- `root-wildcard.test.ts` — transparent root catch-all `/**:path`: must never |
| 165 | + 200 for `/entry-client.ts` under `script`/`style`/`image`/absent dests |
| 166 | + (#4234/#4266), navigations still reach it. |
| 167 | +- `baseurl-dotted-param.test.ts` — explicit splat routes under `baseURL: |
| 168 | + /subdir/`: #4241, #4252, #4270, query-string extension, unmatched asset → |
| 169 | + Vite. |
| 170 | +- Tangential: `hmr.test.ts` (existing module served by Vite under `script` |
| 171 | + dest), `openapi.test.ts` (explicit routes), others (build/env, not routing). |
| 172 | + |
| 173 | +## 8. Gotchas |
| 174 | + |
| 175 | +- The `server.middlewares.stack` scan in `nitroDevMiddleware` skips requests |
| 176 | + whose URL starts with any other middleware's mounted `base` (#3805). |
| 177 | +- `_nitroHandled` is a one-way latch set by the pre-pass (transparent |
| 178 | + catch-all asset) and by the post catch-all itself (re-entry guard). Never set |
| 179 | + it for a request a real or opaque handler should still see (#4252 root |
| 180 | + cause). |
| 181 | +- Extension detection must stay path-only (strip `?#`) and `ASSET_EXT_RE` must |
| 182 | + stay narrow, or dotted Nitro params regress (#4108). |
| 183 | +- `PAGE_CONTENT_RE` must not grow `text/plain` (bridge default for string |
| 184 | + returns) and inspection must only apply to `envRes.ok` — framework 404 pages |
| 185 | + and redirects pass through verbatim. |
| 186 | +- The websocket `upgrade` handler is a separate concern sharing the "Vite's or |
| 187 | + Nitro's?" theme. |
0 commit comments