Separate server middleware to apply +middlewares

[brillout]

Description

While the main goal of renderPage() is to SSR a page, it also adds all Universal Middlewares registered via +middleware — how can these middlewares be applied to all URLs (not just when SSR'ing the page)?

I guess we'll need a separate server middleware, in addition to renderPage().

See also:

• Telefunc seam: collapse dev/prod wiring once the auto-middleware can carry context suleimansh/vike-data#128
• Vike extension telefunc/telefunc#381

[brillout]

Design proposal: standalone middleware runner for +middleware

Where we are today

+middleware entries are collected into globalContext.config.middleware (EnhancedMiddleware | EnhancedMiddleware[], see packages/vike/src/types/Config.ts:666) and are applied only inside renderPageServer():

• renderPageServer.ts:175 flattens globalContext.config.middleware into middlewares.
• renderPageServer.ts:177-181 branches to renderPageServerEntryWithMiddlewares() when there's at least one.
• renderPageServerEntryWithMiddlewares() (renderPageServer.ts:371-416) spins up a UniversalRouter, registers Vike's core page-rendering handler at path /** (renderPageServer.ts:379-400) plus the user middlewares on top, and runs the request through it.

So the middlewares run as part of rendering. Because renderPage() is almost always the catch-all SSR handler (last in the chain — see pluginDev.ts:44 "The SSR middleware should be last middleware", and addSsrMiddleware.ts), the middlewares effectively run last too.

Why this is limiting

1. Can't run before other handlers. Any middleware/route registered before Vike's catch-all intercepts the request first, so the +middleware middlewares never see it.
2. Doesn't cover non-render URLs in the way users expect. They only fire for requests that actually reach renderPage().
3. Dev ≠ prod. This is the crux of Telefunc seam: collapse dev/prod wiring once the auto-middleware can carry context suleimansh/vike-data#128: in production with vike/fetch (fetch.ts → universal-middleware.ts → renderPageServer) as the catch-all, a POST /_telefunc middleware does fire because the request reaches Vike's handler. In dev, Telefunc auto-installs its own Vite dev middleware that intercepts /_telefunc before Vike's catch-all, so the +middleware version never runs. Same config, different behavior.

The shared root cause: middleware application is coupled to, and positioned by, page rendering. The fix is to make it a server middleware that can be positioned independently — exactly the "separate server middleware, in addition to renderPage()" from the description.

Proposed design

Since +middleware entries are already universal-middleware objects, expose them as a standalone universal-middleware runner that any server (or @universal-middleware's apply()) can register early, decoupled from rendering.

1. Runtime: a middlewares-only runner. Factor the router-building logic out of renderPageServerEntryWithMiddlewares() so the same machinery can run the user middlewares without the Vike core /** handler. Semantics: run the registered middlewares; if one returns a Response, short-circuit with it; otherwise fall through (next() / next handler). This relies on universal-middleware's middleware-vs-handler distinction, so true pass-through middlewares (auth, context injection, logging) work, not just terminal handlers like the current /middleware and /_telefunc examples.

2. Public surface. The resolved list currently lives on the internal global context (getGlobalContextServerInternal().globalContext.config.middleware); the public getGlobalContext() doesn't expose it. So we'd add one of:

• getUniversalMiddlewares(): Promise<EnhancedMiddleware[]> — returns the resolved list; callers compose it themselves via apply(server, [...await getUniversalMiddlewares(), vikeRenderHandler]). Most flexible, idiomatic for universal-middleware.
• or a ready-to-use handler export (e.g. a named export from vike/universal-middleware) that internally runs the middlewares — less flexible but zero-assembly for adapters.

Either needs global context initialized; a lazy wrapper (resolve on first request) avoids an await at server-startup registration time.

3. Avoid double-application. If the standalone runner already ran the middlewares for a request, renderPage() must not re-run them (side-effectful middlewares would fire twice). I'd mark the request — a symbol on the universal context/request, or a pageContextInit flag — that the standalone runner sets and renderPageServer.ts:177 checks before taking the renderPageServerEntryWithMiddlewares() branch.

4. Dev + preview wiring. Register the standalone runner as a connect middleware before addSsrMiddleware() (pluginDev.ts for dev, pluginPreview.ts for preview) so +middleware applies to all URLs in Vike's own dev/preview server and matches prod. Caveat worth calling out: Vike can place its runner early (order: 'pre'), but can't guarantee precedence over every third-party Vite dev plugin (Telefunc registers via its own plugin). Fully closing the vike-data#128 dev gap may still need a Telefunc-side hook — but a Vike-positioned early runner is the necessary half.

Decisions that are yours to make

1. Keep middleware application in renderPage() (with a skip-marker when the standalone runner ran) — or move it out entirely? Keeping it is backward-compatible for users who register only renderPage(); moving it out is cleaner but breaks manual renderPage()-only setups unless they also add the standalone runner. My lean: keep + skip-marker, since it's non-breaking and the standalone runner is purely additive.
2. API surface: returned EnhancedMiddleware[] (composes with apply()) vs. a ready-made handler export?
3. Adapter rollout: @vikejs/express, @vikejs/hono, @vikejs/cloudflare, and vike/fetch/vike/universal-middleware would each register the standalone runner first, then the render handler — a coordinated release across those repos.
4. Naming / export path for the new surface.

Happy to implement once you've picked (1) and (2) — the runtime refactor (extracting the runner from renderPageServerEntryWithMiddlewares()) + the skip-marker + dev/preview wiring is self-contained within this repo; the adapter registrations are the cross-repo follow-up.

---

Generated by Claude Code

[brillout]

1. We can move out => AFAIK no user currently uses +middlewares => no breaking change
2. I don't see a problem with EnhancedMiddleware[], so let's go for it
3. Ok, but let's avoid breaking changes here if possible (users are already using these adapters)
4. getUniversalMiddlewares() (function and export path share the same name)