Support rewrite request (Similarly to redirect) (#7562)

* WIP

* handleRewrite WIP

* distinguish between redirect and rewrite

* header property Location is a specific header meant for redirects, removing it breaks redirects

* rewrite finally doesnt throw error > behaves as redirect if the status isnt a 301+. still WIP, need to remove consoles.

* WIP - rewrite somewhat works

* Rewrite works.

* remove console logs

* fix unreadable condition + remove leftover log

* bring back accidental deleted log

* tidy up before tests

* support rewrite for URL objects

* minor rename

* properly handle urls+pathnames+searchparams

* more readable loadedRoute handling. fixed params assignement issue

* fix some types. WIP e2e tests - for some reason not working due to pathname missmatch

* attempt to fix the rewrite in preview - no luck

* texts

* fix preview whitescreen.

* introduce canonicalUrl - to know the request's original url

* everything works including e2e's. will write some more and we're good to go

* everything works well.

* bump

* docs

* remove logs

* minor simplification

* more self pr

* fixed it all, finally.

* api updated

* CR fixes

* minor docs change

* minor docs change

* CR fixes -2-

* CR fixes

* make it experimental

* Fix the FF issues.

* re-add bad error description

Author: omerman

.changeset/dirty-dolls-heal.md

@@ -0,0 +1,19 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+FEAT: Added rewrite() to the RequestEvent object. It works like redirect but does not change the URL,
+      think of it as an internal redirect.
+
+Example usage:
+```ts
+export const onRequest: RequestHandler = async ({ url, rewrite }) => {
+  if (url.pathname.includes("/articles/the-best-article-in-the-world")) {
+    const artistId = db.getArticleByName("the-best-article-in-the-world");
+
+    // Url will remain /articles/the-best-article-in-the-world, but under the hood,
+    // will render /articles/${artistId}
+    throw rewrite(`/articles/${artistId}`);
+  }
+};
+```

packages/docs/src/routes/api/qwik-city-middleware-request-handler/api.json

@@ -717,6 +717,12 @@ Headers
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/cookie.ts)
 
+## pathname
+
+```typescript
+readonly pathname: string;
+```
+
 ## RedirectMessage
 
 ```typescript
@@ -1020,6 +1026,29 @@ https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
 </td></tr>
 <tr><td>
 
+[originalUrl](#)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+URL
+
+</td><td>
+
+The original HTTP request URL.
+
+This property was introduced to support the rewrite feature.
+
+If rewrite is called, the url property will be changed to the rewritten url. while originalUrl will stay the same(e.g the url inserted to the address bar).
+
+If rewrite is never called as part of the request, the url property and the originalUrl are equal.
+
+</td></tr>
+<tr><td>
+
 [params](#)
 
 </td><td>
@@ -1312,6 +1341,25 @@ https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections
 </td></tr>
 <tr><td>
 
+[rewrite](#)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+(pathname: string) =&gt; [RewriteMessage](#rewritemessage)
+
+</td><td>
+
+When called, qwik-city will execute the path's matching route flow.
+
+The url in the browser will remain unchanged.
+
+</td></tr>
+<tr><td>
+
 [send](#)
 
 </td><td>
@@ -1462,6 +1510,76 @@ export interface ResolveValue
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/types.ts)
 
+## RewriteMessage
+
+```typescript
+export declare class RewriteMessage extends AbortMessage
+```
+
+**Extends:** [AbortMessage](#abortmessage)
+
+<table><thead><tr><th>
+
+Constructor
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[(constructor)(pathname)](#)
+
+</td><td>
+
+</td><td>
+
+Constructs a new instance of the `RewriteMessage` class
+
+</td></tr>
+</tbody></table>
+
+<table><thead><tr><th>
+
+Property
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[pathname](#rewritemessage-pathname)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+string
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/rewrite-handler.ts)
+
 ## ServerError
 
 ```typescript

packages/docs/src/routes/api/qwik-city-middleware-request-handler/index.mdx

@@ -106,6 +106,23 @@
       "content": "```typescript\ndirname(path: string): string;\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\npath\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nstring",
       "mdFile": "qwik.path.dirname.md"
     },
+    {
+      "name": "enableRequestRewrite",
+      "id": "experimentalfeatures-enablerequestrewrite",
+      "hierarchy": [
+        {
+          "name": "ExperimentalFeatures",
+          "id": "experimentalfeatures-enablerequestrewrite"
+        },
+        {
+          "name": "enableRequestRewrite",
+          "id": "experimentalfeatures-enablerequestrewrite"
+        }
+      ],
+      "kind": "EnumMember",
+      "content": "",
+      "mdFile": "qwik.experimentalfeatures.enablerequestrewrite.md"
+    },
     {
       "name": "EntryStrategy",
       "id": "entrystrategy",
@@ -130,7 +147,7 @@
         }
       ],
       "kind": "Enum",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nenableRequestRewrite\n\n\n</td><td>\n\n`\"enableRequestRewrite\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable request.rewrite()\n\n\n</td></tr>\n<tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/optimizer/src/plugins/plugin.ts",
       "mdFile": "qwik.experimentalfeatures.md"
     },

packages/docs/src/routes/api/qwik-optimizer/api.json

@@ -325,6 +325,8 @@ string
 
 string
 
+## enableRequestRewrite
+
 ## EntryStrategy
 
 ```typescript
@@ -369,6 +371,19 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+enableRequestRewrite
+
+</td><td>
+
+`"enableRequestRewrite"`
+
+</td><td>
+
+**_(ALPHA)_** Enable request.rewrite()
+
+</td></tr>
+<tr><td>
+
 noSPA
 
 </td><td>

packages/docs/src/routes/api/qwik-optimizer/index.mdx

@@ -0,0 +1,45 @@
+---
+title: Rewrites | Guides
+description: Learn how to use rewrites in Qwik City.
+contributors:
+  - omerman
+updated_at: '2025-05-04T19:43:33Z'
+created_at: '2025-05-04T23:45:13Z'
+---
+
+# Rewrites
+
+Sometimes you want to redirect a user from the current page to another page,
+but you want to keep the current URL in the browser history.
+
+Let's say a user tries to access an article which is indexed by its name,
+e.g `/articles/qwik-is-very-quick`.
+but in our code, we access it by its id, on our directory structure.
+
+```
+src/routes/articles/
+├── [id]
+├─── index.tsx
+```
+
+
+```tsx title="src/routes/[email protected]"
+import type { RequestHandler } from "@builder.io/qwik-city";
+
+export const onRequest: RequestHandler = async ({ url, rewrite }) => {
+  const pattern = /^\/articles\/(.*)$/;
+  // Detects /articles/<article-name>, returns null if url does not match the pattern.
+  const match = url.pathname.match(pattern);
+  if (match) {
+    const articleName = match[1];
+    const { id } = await db.getArticleByName(articleName);
+    throw rewrite(`/articles/${id}`);
+  }
+};
+```
+
+The `rewrite()` function, which was destructured in the RequestHandler function arguments, is invoked with a pathname string.
+
+```tsx
+throw rewrite(`/articles/777/`);
+```

packages/docs/src/routes/docs/(qwikcity)/guides/rewrites/index.mdx

@@ -18,6 +18,7 @@ import { matchRoute } from '../../runtime/src/route-matcher';
 import { getMenuLoader } from '../../runtime/src/routing';
 import type {
   ActionInternal,
+  RebuildRouteInfoInternal,
   ContentMenu,
   LoadedRoute,
   LoaderInternal,
@@ -227,10 +228,27 @@ export function ssrDevMiddleware(ctx: BuildContext, server: ViteDevServer) {
             await server.ssrLoadModule('@qwik-serializer');
           const qwikSerializer = { _deserializeData, _serializeData, _verifySerializable };
 
+          const rebuildRouteInfo: RebuildRouteInfoInternal = async (url: URL) => {
+            const { serverPlugins, loadedRoute } = await resolveRoute(routeModulePaths, url);
+            const requestHandlers = resolveRequestHandlers(
+              serverPlugins,
+              loadedRoute,
+              req.method ?? 'GET',
+              false,
+              renderFn
+            );
+
+            return {
+              loadedRoute,
+              requestHandlers,
+            };
+          };
+
           const { completion, requestEv } = runQwikCity(
             serverRequestEv,
             loadedRoute,
             requestHandlers,
+            rebuildRouteInfo,
             ctx.opts.trailingSlash,
             ctx.opts.basePathname,
             qwikSerializer

packages/qwik-city/src/buildtime/vite/dev-server.ts

@@ -1,6 +1,7 @@
 export { getErrorHtml, ServerError } from './error-handler';
 export { mergeHeadersCookies } from './cookie';
 export { AbortMessage, RedirectMessage } from './redirect-handler';
+export { RewriteMessage } from './rewrite-handler';
 export { requestHandler } from './request-handler';
 export { _TextEncoderStream_polyfill } from './polyfill';
 export type {

packages/qwik-city/src/middleware/request-handler/index.ts

@@ -112,6 +112,7 @@ export interface RequestEventBase<PLATFORM = QwikCityPlatform> {
     readonly env: EnvGetter;
     readonly headers: Headers;
     readonly method: string;
+    readonly originalUrl: URL;
     readonly params: Readonly<Record<string, string>>;
     readonly parseBody: () => Promise<unknown>;
     readonly pathname: string;
@@ -134,6 +135,7 @@ export interface RequestEventCommon<PLATFORM = QwikCityPlatform> extends Request
     readonly locale: (local?: string) => string;
     // Warning: (ae-forgotten-export) The symbol "RedirectCode" needs to be exported by the entry point index.d.ts
     readonly redirect: (statusCode: RedirectCode, url: string) => RedirectMessage;
+    readonly rewrite: (pathname: string) => RewriteMessage;
     // Warning: (ae-forgotten-export) The symbol "SendMethod" needs to be exported by the entry point index.d.ts
     readonly send: SendMethod;
     // Warning: (ae-forgotten-export) The symbol "StatusCodes" needs to be exported by the entry point index.d.ts
@@ -174,6 +176,13 @@ export interface ResolveValue {
     <T>(action: Action<T>): Promise<T | undefined>;
 }
 
+// @public (undocumented)
+export class RewriteMessage extends AbortMessage {
+    constructor(pathname: string);
+    // (undocumented)
+    readonly pathname: string;
+}
+
 // @public (undocumented)
 export class ServerError<T = any> extends Error {
     constructor(status: number, data: T);