From 46740e6cd3b4c71cc42bdb99fff2abd7a6694f36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= <seb@nuxtlabs.com>
Date: Tue, 18 Apr 2023 10:37:39 +0200
Subject: [PATCH] docs(routing): add route rules

---
 docs/content/1.guide/3.routing.md | 59 ++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/docs/content/1.guide/3.routing.md b/docs/content/1.guide/3.routing.md
index 2c97ba618e..a3c6be360a 100644
--- a/docs/content/1.guide/3.routing.md
+++ b/docs/content/1.guide/3.routing.md
@@ -3,7 +3,11 @@ title: Routing
 icon: ri:direction-line
 ---
 
-# Filesystem Routing
+# Routing
+
+Nitro support filesystem routing as well as defining route rules for maximum flexibility and performance.
+
+## Filesystem Routing
 
 Nitro supports file-based routing for your API routes.
 
@@ -13,8 +17,6 @@ Handler files inside `api/` and `routes/` directory will be automatically mapped
 Due to some providers like Vercel using  top-level `api/` directory as a feature, Nitro also supports `routes/api/` to create API routes.
 ::
 
-## Usage
-
 ```md
 api/
   test.ts      <-- /api/test
@@ -23,8 +25,9 @@ routes/
 nitro.config.ts
 ```
 
+::alert
 If you are using [Nuxt](https://nuxt.com), move the `api/` and `routes/` inside the `server/` directory.
-
+::
 
 ### Simple route
 
@@ -96,3 +99,51 @@ Check out [h3 JSDocs](https://www.jsdocs.io/package/h3#package-index-functions)
 export default eventHandler(event => `Default page`)
 ```
 
+## Route Rules
+
+Nitro allows you to add logic at the top-level of your configuration, useful for redirecting, proxying, caching and adding headers to routes.
+
+It is a map from route pattern (following [unjs/radix3](https://github.com/unjs/radix3#route-matcher)) to route options.
+
+When `cache` option is set, handlers matching pattern will be automatically wrapped with `defineCachedEventHandler`.
+
+ See the [Cache API](/guide/cache) for all available cache options.
+
+::alert
+`swr: true|number` is shortcut for `cache: { swr: true, maxAge: number }`
+::
+
+**Example:**
+
+::code-group
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  routeRules: {
+    '/blog/**': { swr: true },
+    '/blog/**': { swr: 600 },
+    '/blog/**': { static: true },
+    '/blog/**': { cache: { /* cache options*/ } },
+    '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
+    '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
+    '/old-page': { redirect: '/new-page' },
+    '/proxy/example': { proxy: 'https://example.com' },
+    '/proxy/**': { proxy: '/api/**' },
+  }
+})
+```
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/blog/**': { swr: true },
+    '/blog/**': { swr: 600 },
+    '/blog/**': { static: true },
+    '/blog/**': { cache: { /* cache options*/ } },
+    '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
+    '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
+    '/old-page': { redirect: '/new-page' },
+    '/proxy/example': { proxy: 'https://example.com' },
+    '/proxy/**': { proxy: '/api/**' },
+  }
+})
+```
+::