feat(docs): `extendRouteRules`

docs/3.api/4.advanced/2.kit.md

@@ -1282,7 +1282,121 @@ export default defineNuxtModule({
 })
 ```
 
-- `extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)`
+### `extendRouteRules`
+
+Nuxt is powered by the [Nitro](https://nitro.unjs.io) server engine. With Nitro, you can incorporate high-level logic directly into your configuration, which is usefull for actions like redirects, proxying, caching, and appending headers to routes. This configuration works by associating route patterns with specific route settings.
+
+::alert{type=info icon=👉}
+You can read more about Nitro route rules in the [Nitro documentation](https://nitro.unjs.io/guide/routing#route-rules).
+::
+
+#### Type
+
+```ts
+function extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)
+
+interface NitroRouteConfig {
+  cache?: CacheOptions | false;
+  headers?: Record<string, string>;
+  redirect?: string | { to: string; statusCode?: HTTPStatusCode };
+  prerender?: boolean;
+  proxy?: string | ({ to: string } & ProxyOptions);
+  isr?: number | boolean;
+  cors?: boolean;
+  swr?: boolean | number;
+  static?: boolean | number;
+}
+
+interface ExtendRouteRulesOptions {
+  override?: boolean
+}
+
+interface CacheOptions {
+  swr?: boolean
+  name?: string
+  group?: string
+  integrity?: any
+  maxAge?: number
+  staleMaxAge?: number
+  base?: string
+  headersOnly?: boolean
+}
+
+// See https://www.jsdocs.io/package/h3#ProxyOptions
+interface ProxyOptions {
+  headers?: RequestHeaders | HeadersInit;
+  fetchOptions?: RequestInit & { duplex?: Duplex } & {
+    ignoreResponseError?: boolean;
+  };
+  fetch?: typeof fetch;
+  sendStream?: boolean;
+  streamRequest?: boolean;
+  cookieDomainRewrite?: string | Record<string, string>;
+  cookiePathRewrite?: string | Record<string, string>;
+  onResponse?: (event: H3Event, response: Response) => void;
+}
+```
+
+#### Parameters
+
+##### `route`
+
+**Type**: `string`
+
+**Required**: `true`
+
+A route pattern to match against.
+
+##### `rule`
+
+**Type**: `NitroRouteConfig`
+
+**Required**: `true`
+
+A route configuration to apply to the matched route.
+
+##### `options`
+
+**Type**: `ExtendRouteRulesOptions`
+
+**Default**: `{}`
+
+Options to pass to the route configuration. If `override` is set to `true`, it will override the existing route configuration.
+
+#### Examples
+
+```ts
+// https://github.com/directus/website/blob/main/modules/redirects.ts
+import { createResolver, defineNuxtModule, extendRouteRules, extendPages } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+
+    extendPages((pages) => {
+      pages.unshift({
+        name: 'preview-new',
+        path: '/preview-new',
+        file: resolver.resolve('runtime/preview.vue')
+       })
+    })
+
+    extendRouteRules('/preview', {
+      redirect: {
+        to: '/preview-new',
+        statusCode: 302
+      }
+    })
+
+    extendRouteRules('/preview-new', {
+      cache: {
+        maxAge: 60 * 60 * 24 * 7
+      }
+    })
+  }
+})
+```
+
 - `addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options: AddRouteMiddlewareOptions)`
 
 ## Plugins