From 8d832c88149073029b4b09ed017ee772035f9f45 Mon Sep 17 00:00:00 2001 From: Barbapapazes Date: Tue, 13 Jun 2023 09:49:59 +0200 Subject: [PATCH 1/6] docs: add middlewares --- docs/content/1.guide/4.middlewares.md | 84 +++++++++++++++++++ .../1.guide/{4.storage.md => 5.storage.md} | 0 .../1.guide/{5.cache.md => 6.cache.md} | 0 .../1.guide/{6.assets.md => 7.assets.md} | 0 .../1.guide/{7.plugins.md => 8.plugins.md} | 0 .../{8.typescript.md => 9.typescript.md} | 0 6 files changed, 84 insertions(+) create mode 100644 docs/content/1.guide/4.middlewares.md rename docs/content/1.guide/{4.storage.md => 5.storage.md} (100%) rename docs/content/1.guide/{5.cache.md => 6.cache.md} (100%) rename docs/content/1.guide/{6.assets.md => 7.assets.md} (100%) rename docs/content/1.guide/{7.plugins.md => 8.plugins.md} (100%) rename docs/content/1.guide/{8.typescript.md => 9.typescript.md} (100%) diff --git a/docs/content/1.guide/4.middlewares.md b/docs/content/1.guide/4.middlewares.md new file mode 100644 index 0000000000..39be254e59 --- /dev/null +++ b/docs/content/1.guide/4.middlewares.md @@ -0,0 +1,84 @@ +--- +title: Middlewares +icon: ri:shield-user-line +--- + +# Middlewares + +Nitro supports globals middlewares to hook into the request lifecycle. + +::alert{type=primary} +Middlewares can only interact before the request is processed. +:: + +Middlewares are auto-registered withing the `middlewares/` directory. + +```md +routes/ + hello.ts +middlewares/ + auth.ts + logger.ts + ... +nitro.config.ts +``` + +## Simple middleware + +Middleware is defined as a route handler. You can use every composables available in Nitro in your middleware. + +```ts [middlewares/auth.ts] +export default defineEventHandler((event) => { + // Extends or modify the event + event.context.user = { name: 'Nitro' } +}) +``` + +::alert +Never return anything from a middleware, you will close the request. +:: + +## Order of execution + +Middlewares are executed in the order of the directory listing. + +```md +middlewares/ + auth.ts <-- First + logger.ts <-- Second + ... <-- Third +``` + +You can prefix your middleware with a number to control the order of execution. + +```md +middlewares/ + 1.logger.ts <-- First + 2.auth.ts <-- Second + 3.... <-- Third +``` + +You can also put your middleware in a subdirectory to group them together. + +```md +middlewares/ + auth/ + index.ts + ... + logger/ + index.ts + ... +``` + +## Select routes + +Middlewares are executed for all routes by default. But you can add logic to only execute them for specific routes. + +```ts [middlewares/auth.ts] +export default defineEventHandler((event) => { + if (event.node.req.url?.startsWith('/auth')) { + // Will only execute for /auth route + event.context.user = { name: 'Nitro' } + } +}) +``` diff --git a/docs/content/1.guide/4.storage.md b/docs/content/1.guide/5.storage.md similarity index 100% rename from docs/content/1.guide/4.storage.md rename to docs/content/1.guide/5.storage.md diff --git a/docs/content/1.guide/5.cache.md b/docs/content/1.guide/6.cache.md similarity index 100% rename from docs/content/1.guide/5.cache.md rename to docs/content/1.guide/6.cache.md diff --git a/docs/content/1.guide/6.assets.md b/docs/content/1.guide/7.assets.md similarity index 100% rename from docs/content/1.guide/6.assets.md rename to docs/content/1.guide/7.assets.md diff --git a/docs/content/1.guide/7.plugins.md b/docs/content/1.guide/8.plugins.md similarity index 100% rename from docs/content/1.guide/7.plugins.md rename to docs/content/1.guide/8.plugins.md diff --git a/docs/content/1.guide/8.typescript.md b/docs/content/1.guide/9.typescript.md similarity index 100% rename from docs/content/1.guide/8.typescript.md rename to docs/content/1.guide/9.typescript.md From 0e612801717a9e9b7ef31212b2114937a3a2bc78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Est=C3=A9ban?= Date: Sun, 18 Jun 2023 07:59:21 +0200 Subject: [PATCH 2/6] Update docs/content/1.guide/4.middlewares.md --- docs/content/1.guide/4.middlewares.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/1.guide/4.middlewares.md b/docs/content/1.guide/4.middlewares.md index 39be254e59..54aa839986 100644 --- a/docs/content/1.guide/4.middlewares.md +++ b/docs/content/1.guide/4.middlewares.md @@ -11,7 +11,7 @@ Nitro supports globals middlewares to hook into the request lifecycle. Middlewares can only interact before the request is processed. :: -Middlewares are auto-registered withing the `middlewares/` directory. +Middlewares are auto-registered within the `middlewares/` directory. ```md routes/ From 5558a136dca51b1d2f86670095081796667a6e6b Mon Sep 17 00:00:00 2001 From: Hebilicious Date: Sun, 2 Jul 2023 04:24:40 +0700 Subject: [PATCH 3/6] docs: fix grammar --- docs/content/1.guide/4.middlewares.md | 35 ++++++++++++++------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/content/1.guide/4.middlewares.md b/docs/content/1.guide/4.middlewares.md index 54aa839986..352a205227 100644 --- a/docs/content/1.guide/4.middlewares.md +++ b/docs/content/1.guide/4.middlewares.md @@ -1,22 +1,21 @@ --- -title: Middlewares icon: ri:shield-user-line --- # Middlewares -Nitro supports globals middlewares to hook into the request lifecycle. +Nitro middlewares can hook into the request lifecycle. ::alert{type=primary} -Middlewares can only interact before the request is processed. +A middleware can modify the request before it is processed, not after. :: -Middlewares are auto-registered within the `middlewares/` directory. +Middlewares are auto-registered within the `middleware/` directory. ```md routes/ hello.ts -middlewares/ +middleware/ auth.ts logger.ts ... @@ -25,9 +24,9 @@ nitro.config.ts ## Simple middleware -Middleware is defined as a route handler. You can use every composables available in Nitro in your middleware. +Middlewares are defined exactly like route handlers. -```ts [middlewares/auth.ts] +```ts [middleware/auth.ts] export default defineEventHandler((event) => { // Extends or modify the event event.context.user = { name: 'Nitro' } @@ -35,21 +34,21 @@ export default defineEventHandler((event) => { ``` ::alert -Never return anything from a middleware, you will close the request. +Returning anything from a middleware will close the request. :: -## Order of execution +## Execution order -Middlewares are executed in the order of the directory listing. +Middlewares are executed in directory listing order. ```md -middlewares/ +middleware/ auth.ts <-- First logger.ts <-- Second ... <-- Third ``` -You can prefix your middleware with a number to control the order of execution. +Prefix middlewares with a number to control their execution order. ```md middlewares/ @@ -58,7 +57,7 @@ middlewares/ 3.... <-- Third ``` -You can also put your middleware in a subdirectory to group them together. +Middlewares can be grouped in subdirectories. ```md middlewares/ @@ -70,14 +69,16 @@ middlewares/ ... ``` -## Select routes +## Request filtering -Middlewares are executed for all routes by default. But you can add logic to only execute them for specific routes. +Middlewares are executed on every request. +Apply custom logic to scope them to specific conditions. +For example, you can use the URL to apply a middleware to a specific route : ```ts [middlewares/auth.ts] export default defineEventHandler((event) => { - if (event.node.req.url?.startsWith('/auth')) { - // Will only execute for /auth route + // Will only execute for /auth route + if (getRequestURL(event).startsWith('/auth')) { event.context.user = { name: 'Nitro' } } }) From 387dd3d970a86d9fe0a35ccde9376af429c454d5 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Sun, 6 Aug 2023 22:36:53 +0200 Subject: [PATCH 4/6] update --- .../{4.middlewares.md => 4.middleware.md} | 40 +++++++------------ 1 file changed, 15 insertions(+), 25 deletions(-) rename docs/content/1.guide/{4.middlewares.md => 4.middleware.md} (56%) diff --git a/docs/content/1.guide/4.middlewares.md b/docs/content/1.guide/4.middleware.md similarity index 56% rename from docs/content/1.guide/4.middlewares.md rename to docs/content/1.guide/4.middleware.md index 352a205227..92da08ffee 100644 --- a/docs/content/1.guide/4.middlewares.md +++ b/docs/content/1.guide/4.middleware.md @@ -2,15 +2,15 @@ icon: ri:shield-user-line --- -# Middlewares +# Middleware -Nitro middlewares can hook into the request lifecycle. +Nitro middleware can hook into the request lifecycle. ::alert{type=primary} A middleware can modify the request before it is processed, not after. :: -Middlewares are auto-registered within the `middleware/` directory. +Middleware are auto-registered within the `middleware/` directory. ```md routes/ @@ -22,9 +22,9 @@ middleware/ nitro.config.ts ``` -## Simple middleware +## Simple Middleware -Middlewares are defined exactly like route handlers. +Middleware are defined exactly like route handlers with the only exception that they should not return anything. ```ts [middleware/auth.ts] export default defineEventHandler((event) => { @@ -34,12 +34,12 @@ export default defineEventHandler((event) => { ``` ::alert -Returning anything from a middleware will close the request. +Returning anything from a middleware will close the request and should be avoided! :: -## Execution order +## Execution Order -Middlewares are executed in directory listing order. +Middleware are executed in directory listing order. ```md middleware/ @@ -48,34 +48,24 @@ middleware/ ... <-- Third ``` -Prefix middlewares with a number to control their execution order. +Prefix middleware with a number to control their execution order. ```md -middlewares/ +middleware/ 1.logger.ts <-- First 2.auth.ts <-- Second 3.... <-- Third ``` -Middlewares can be grouped in subdirectories. - -```md -middlewares/ - auth/ - index.ts - ... - logger/ - index.ts - ... -``` +## Request Filtering -## Request filtering +Middleware are executed on every request. -Middlewares are executed on every request. Apply custom logic to scope them to specific conditions. -For example, you can use the URL to apply a middleware to a specific route : -```ts [middlewares/auth.ts] +For example, you can use the URL to apply a middleware to a specific route: + +```ts [middleware/auth.ts] export default defineEventHandler((event) => { // Will only execute for /auth route if (getRequestURL(event).startsWith('/auth')) { From e13121edb30db46cbcefa5966f981f1433693c60 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Sun, 6 Aug 2023 22:40:29 +0200 Subject: [PATCH 5/6] merge to routing --- docs/content/1.guide/3.routing.md | 74 ++++++++++++++++++ docs/content/1.guide/4.middleware.md | 75 ------------------- .../1.guide/{5.storage.md => 4.storage.md} | 0 .../1.guide/{6.cache.md => 5.cache.md} | 0 .../1.guide/{7.assets.md => 6.assets.md} | 0 .../1.guide/{8.plugins.md => 7.plugins.md} | 0 .../{9.typescript.md => 8.typescript.md} | 0 7 files changed, 74 insertions(+), 75 deletions(-) delete mode 100644 docs/content/1.guide/4.middleware.md rename docs/content/1.guide/{5.storage.md => 4.storage.md} (100%) rename docs/content/1.guide/{6.cache.md => 5.cache.md} (100%) rename docs/content/1.guide/{7.assets.md => 6.assets.md} (100%) rename docs/content/1.guide/{8.plugins.md => 7.plugins.md} (100%) rename docs/content/1.guide/{9.typescript.md => 8.typescript.md} (100%) diff --git a/docs/content/1.guide/3.routing.md b/docs/content/1.guide/3.routing.md index 4871c1ac41..80d889d713 100644 --- a/docs/content/1.guide/3.routing.md +++ b/docs/content/1.guide/3.routing.md @@ -149,3 +149,77 @@ export default defineNuxtConfig({ }) ``` :: + + + +## Route Middleware + +Nitro route middleware can hook into the request lifecycle. + +::alert{type=primary} +A middleware can modify the request before it is processed, not after. +:: + +Middleware are auto-registered within the `middleware/` directory. + +```md +routes/ + hello.ts +middleware/ + auth.ts + logger.ts + ... +nitro.config.ts +``` + +### Simple Middleware + +Middleware are defined exactly like route handlers with the only exception that they should not return anything. + +```ts [middleware/auth.ts] +export default defineEventHandler((event) => { + // Extends or modify the event + event.context.user = { name: 'Nitro' } +}) +``` + +::alert +Returning anything from a middleware will close the request and should be avoided! +:: + +### Execution Order + +Middleware are executed in directory listing order. + +```md +middleware/ + auth.ts <-- First + logger.ts <-- Second + ... <-- Third +``` + +Prefix middleware with a number to control their execution order. + +```md +middleware/ + 1.logger.ts <-- First + 2.auth.ts <-- Second + 3.... <-- Third +``` + +### Request Filtering + +Middleware are executed on every request. + +Apply custom logic to scope them to specific conditions. + +For example, you can use the URL to apply a middleware to a specific route: + +```ts [middleware/auth.ts] +export default defineEventHandler((event) => { + // Will only execute for /auth route + if (getRequestURL(event).startsWith('/auth')) { + event.context.user = { name: 'Nitro' } + } +}) +``` diff --git a/docs/content/1.guide/4.middleware.md b/docs/content/1.guide/4.middleware.md deleted file mode 100644 index 92da08ffee..0000000000 --- a/docs/content/1.guide/4.middleware.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -icon: ri:shield-user-line ---- - -# Middleware - -Nitro middleware can hook into the request lifecycle. - -::alert{type=primary} -A middleware can modify the request before it is processed, not after. -:: - -Middleware are auto-registered within the `middleware/` directory. - -```md -routes/ - hello.ts -middleware/ - auth.ts - logger.ts - ... -nitro.config.ts -``` - -## Simple Middleware - -Middleware are defined exactly like route handlers with the only exception that they should not return anything. - -```ts [middleware/auth.ts] -export default defineEventHandler((event) => { - // Extends or modify the event - event.context.user = { name: 'Nitro' } -}) -``` - -::alert -Returning anything from a middleware will close the request and should be avoided! -:: - -## Execution Order - -Middleware are executed in directory listing order. - -```md -middleware/ - auth.ts <-- First - logger.ts <-- Second - ... <-- Third -``` - -Prefix middleware with a number to control their execution order. - -```md -middleware/ - 1.logger.ts <-- First - 2.auth.ts <-- Second - 3.... <-- Third -``` - -## Request Filtering - -Middleware are executed on every request. - -Apply custom logic to scope them to specific conditions. - -For example, you can use the URL to apply a middleware to a specific route: - -```ts [middleware/auth.ts] -export default defineEventHandler((event) => { - // Will only execute for /auth route - if (getRequestURL(event).startsWith('/auth')) { - event.context.user = { name: 'Nitro' } - } -}) -``` diff --git a/docs/content/1.guide/5.storage.md b/docs/content/1.guide/4.storage.md similarity index 100% rename from docs/content/1.guide/5.storage.md rename to docs/content/1.guide/4.storage.md diff --git a/docs/content/1.guide/6.cache.md b/docs/content/1.guide/5.cache.md similarity index 100% rename from docs/content/1.guide/6.cache.md rename to docs/content/1.guide/5.cache.md diff --git a/docs/content/1.guide/7.assets.md b/docs/content/1.guide/6.assets.md similarity index 100% rename from docs/content/1.guide/7.assets.md rename to docs/content/1.guide/6.assets.md diff --git a/docs/content/1.guide/8.plugins.md b/docs/content/1.guide/7.plugins.md similarity index 100% rename from docs/content/1.guide/8.plugins.md rename to docs/content/1.guide/7.plugins.md diff --git a/docs/content/1.guide/9.typescript.md b/docs/content/1.guide/8.typescript.md similarity index 100% rename from docs/content/1.guide/9.typescript.md rename to docs/content/1.guide/8.typescript.md From 06b7ddc7e4eb0260bb36c844174be5db7c7475d2 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Sun, 6 Aug 2023 22:42:18 +0200 Subject: [PATCH 6/6] remove empty space --- docs/content/1.guide/3.routing.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/content/1.guide/3.routing.md b/docs/content/1.guide/3.routing.md index 80d889d713..07c63a2233 100644 --- a/docs/content/1.guide/3.routing.md +++ b/docs/content/1.guide/3.routing.md @@ -150,8 +150,6 @@ export default defineNuxtConfig({ ``` :: - - ## Route Middleware Nitro route middleware can hook into the request lifecycle.