You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: www/apps/book/app/learn/fundamentals/api-routes/middlewares/page.mdx
+185-40
Original file line number
Diff line number
Diff line change
@@ -18,11 +18,20 @@ As Medusa's server is based on Express, you can use any [Express middleware](htt
18
18
19
19
</Note>
20
20
21
+
### Middleware Types
22
+
23
+
There are two types of middlewares:
24
+
25
+
1. Global Middleware: A middleware that applies to all routes matching a specified pattern.
26
+
2. Route Middleware: A middleware that applies to routes matching a specified pattern and HTTP method(s).
27
+
28
+
These middlewares generally have the same definition and usage, but they differ in the routes they apply to. You'll learn how to create both types in the following sections.
29
+
21
30
---
22
31
23
-
## How to Create a Middleware?
32
+
## How to Create a Global Middleware?
24
33
25
-
Middlewares are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
34
+
Middlewares of all types are defined in the special file `src/api/middlewares.ts`. Use the `defineMiddlewares` function from the Medusa Framework to define the middlewares, and export its value.
The `defineMiddlewares` function accepts a middleware configurations object that has the property `routes`. `routes`'s value is an array of middleware route objects, each having the following properties:
58
67
59
68
-`matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
60
-
-`middlewares`: An array of middleware functions.
69
+
-`middlewares`: An array of global and route middleware functions.
70
+
71
+
In the example above, you define a global middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
72
+
73
+
### Test the Global Middleware
74
+
75
+
To test the middleware:
76
+
77
+
1. Start the application:
78
+
79
+
```bash npm2yarn
80
+
npm run dev
81
+
```
61
82
62
-
In the example above, you define a middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.
83
+
2. Send a request to any API route starting with `/custom`.
84
+
3. See the following message in the terminal:
85
+
86
+
```bash
87
+
Received a request!
88
+
```
63
89
64
90
---
65
91
66
-
## Test the Middleware
92
+
## How to Create a Route Middleware?
93
+
94
+
In the previous section, you learned how to create a global middleware. You define the route middleware in the same way in `src/api/middlewares.ts`, but you specify an additional property `method` in the middleware route object. Its value is one or more HTTP methods to apply the middleware to.
95
+
96
+
For example:
97
+
98
+
exportconst highlights = [["12", "method", "Apply the middleware only on `POST` requests"]]
This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`, changing the middleware from a global middleware to a route middleware.
130
+
131
+
### Test the Route Middleware
67
132
68
133
To test the middleware:
69
134
@@ -73,7 +138,7 @@ To test the middleware:
73
138
npm run dev
74
139
```
75
140
76
-
2. Send a request to any API route starting with `/custom`.
141
+
2. Send a `POST`request to any API route starting with `/custom`.
77
142
3. See the following message in the terminal:
78
143
79
144
```bash
@@ -141,15 +206,13 @@ This applies a middleware to the routes defined in the file `src/api/custom/[id]
141
206
142
207
---
143
208
144
-
## Restrict HTTP Methods
145
-
146
-
Restrict which HTTP methods the middleware is applied to using the `method` property of the middleware route object.
209
+
## Request URLs with Trailing Backslashes
147
210
148
-
For example:
211
+
A middleware whose `matcher` pattern doesn't end with a backslash won't be applied for requests to URLs with a trailing backslash.
149
212
150
-
exportconst highlights = [["12", "method", "Apply the middleware only on `POST` requests"]]
213
+
For example, consider you have the following middleware:
If you send a request to `http://localhost:9000/custom`, the middleware will run.
354
+
When you send a request to `/custom` route, the following messages are logged in the terminal:
214
355
215
-
However, if you send a request to `http://localhost:9000/custom/`, the middleware won't run.
356
+
```bash
357
+
Global middleware
358
+
Route middleware
359
+
Hello from custom!# message logged from API route handler
360
+
```
216
361
217
-
In general, avoid adding trailing backslashes when sending requests to API routes.
362
+
The global middleware runs first, then the route middleware, and finally the route handler, assuming that it logs the message `Hello from custom!`.
218
363
219
364
---
220
365
221
-
## Middlewares Precedence in Registration
366
+
## Overriding Middlewares
222
367
223
-
The Medusa application registers your middlewares first, then registers middlewares defined in Medusa's core.
368
+
A middleware can not override an existing middleware. Instead, middlewares are added to the end of the middleware stack.
224
369
225
-
So, if you add a middleware for a route defined in the core, it might get overridden by the core middleware. For example, if you add a middleware to change authentication of admin routes, the authentication middleware defined in the core will still run, leading to your middleware not being effective.
370
+
For example, if you define a custom validation middleware, such as `validateAndTransformBody`, on an existing route, then both the original and the custom validation middleware will run.
0 commit comments