docs: added troubleshooting component (#4255)
This commit is contained in:
Shahed Nasser
GitHub
216
docs/content/development/endpoints/add-middleware.mdx
Normal file
216
docs/content/development/endpoints/add-middleware.mdx
Normal file
@@ -0,0 +1,216 @@
|
||||
---
|
||||
description: 'Learn how to add a middleware in Medusa. A middleware is a function that has access to the request and response objects and can be used to perform actions around an endpoint.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Troubleshooting from '@site/src/components/Troubleshooting'
|
||||
import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md'
|
||||
import CustomRegistrationSection from '../../troubleshooting/awilix-resolution-error/_custom-registration.md'
|
||||
|
||||
# Middlewares
|
||||
|
||||
In this document, you’ll learn how to add a middleware to an existing or custom route in Medusa.
|
||||
|
||||
## Overview
|
||||
|
||||
As the Medusa backend is built on top of [Express](https://expressjs.com/), Express’s features can be utilized during your development with Medusa.
|
||||
|
||||
One feature in particular is adding a [middleware](http://expressjs.com/en/guide/using-middleware.html#using-middleware). A middleware is a function that has access to the request and response objects.
|
||||
|
||||
A middleware can be used to perform an action when an endpoint is called or modify the response, among other usages.
|
||||
|
||||
You can add a middleware to an existing route in the Medusa backend, a route in a plugin, or your custom routes.
|
||||
|
||||
---
|
||||
|
||||
## How to Add a Middleware
|
||||
|
||||
### Step 1: Create the Middleware File
|
||||
|
||||
You can organize your middlewares as you see fit, but it's recommended to create Middlewares in the `src/api/middlewares` directory. It's recommended to create each middleware in a different file.
|
||||
|
||||
Each file should export a middleware function that accepts three parameters:
|
||||
|
||||
1. The first one is an Express request object. It can be used to get details related to the request or resolve resources from the dependency container.
|
||||
2. The second one is an Express response object. It can be used to modify the response, or in some cases return a response without executing the associated endpoint.
|
||||
3. The third one is a next middleware function that ensures that other middlewares and the associated endpoint are executed.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about Middlewares and their capabilities in [Express’s documentation](http://expressjs.com/en/guide/using-middleware.html#using-middleware).
|
||||
|
||||
:::
|
||||
|
||||
Here's an example of a middleware:
|
||||
|
||||
```ts title=src/api/middlewares/custom-middleware.ts
|
||||
export function customMiddleware(req, res, next) {
|
||||
// TODO perform an action
|
||||
|
||||
next()
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Apply Middleware on an Endpoint
|
||||
|
||||
To apply a middleware on any endpoint, you can use the same router defined in `src/api/index.ts` or any other router that is used or exported by `src/api/index.ts`. For example:
|
||||
|
||||
:::warning
|
||||
|
||||
The examples used here don't apply Cross-Origin Resource Origin (CORS) options for simplicity. Make sure to apply them, especially for core routes, as explained in the [Create Endpoint](./create.md#cors-configuration) documentation.
|
||||
|
||||
:::
|
||||
|
||||
```ts title=src/api/index.ts
|
||||
import { Router } from "express"
|
||||
import {
|
||||
customMiddleware,
|
||||
} from "./middlewares/custom-middleware"
|
||||
|
||||
export default (rootDirectory, pluginOptions) => {
|
||||
const router = Router()
|
||||
|
||||
// custom route
|
||||
router.get("/hello", (req, res) => {
|
||||
res.json({
|
||||
message: "Welcome to My Store!",
|
||||
})
|
||||
})
|
||||
|
||||
// middleware for the custom route
|
||||
router.use("/hello", customMiddleware)
|
||||
|
||||
// middleware for core route
|
||||
router.use("/store/products", customMiddleware)
|
||||
|
||||
return router
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3: Building Files
|
||||
|
||||
Similar to custom endpoints, you must transpile the files under `src` into the `dist` directory for the backend to load them.
|
||||
|
||||
To do that, run the following command before running the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
||||
You can then test that the middleware is working by running the backend.
|
||||
|
||||
---
|
||||
|
||||
## Registering New Resources in Dependency Container
|
||||
|
||||
In some cases, you may need to register a resource to use within your commerce application. For example, you may want to register the logged-in user to access it in other services. You can do that in your middleware.
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to register a logged-in user and access it in your resources, you can check out [this example guide](./example-logged-in-user.mdx).
|
||||
|
||||
:::
|
||||
|
||||
To register a new resource in the dependency container, use the `req.scope.register` method:
|
||||
|
||||
```ts title=src/api/middlewares/custom-middleware.ts
|
||||
export function customMiddleware(req, res, next) {
|
||||
// TODO perform an action
|
||||
|
||||
req.scope.register({
|
||||
customResource: {
|
||||
resolve: () => "my custom resource",
|
||||
},
|
||||
})
|
||||
|
||||
next()
|
||||
}
|
||||
```
|
||||
|
||||
You can then load this new resource within other resources. For example, to load it in a service:
|
||||
|
||||
<!-- eslint-disable prefer-rest-params -->
|
||||
|
||||
```ts title=src/services/custom-service.ts
|
||||
import { TransactionBaseService } from "@medusajs/medusa"
|
||||
|
||||
class CustomService extends TransactionBaseService {
|
||||
|
||||
constructor(container, options) {
|
||||
super(...arguments)
|
||||
|
||||
// use the registered resource.
|
||||
try {
|
||||
container.customResource
|
||||
} catch (e) {
|
||||
// avoid errors when the backend first loads
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomService
|
||||
```
|
||||
|
||||
Notice that you have to wrap your usage of the new resource in a try-catch block when you use it in a constructor. This is to avoid errors that can arise when the backend first loads, as the resource is not registered yet.
|
||||
|
||||
### Note About Services Lifetime
|
||||
|
||||
If you want to access new registrations in the dependency container within a service, you must set the lifetime of the service either to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. Services that have a `Lifetime.SINGLETON` lifetime can't access new registrations since they're resolved and cached in the root dependency container beforehand. You can learn more in the [Create Services documentation](../services/create-service.mdx#service-life-time).
|
||||
|
||||
For custom services, no additional action is required as the default lifetime is `Lifetime.SCOPED`. However, if you extend a core service, you must change the lifetime since the default lifetime for core services is `Lifetime.SINGLETON`.
|
||||
|
||||
For example:
|
||||
|
||||
<!-- eslint-disable prefer-rest-params -->
|
||||
|
||||
```ts
|
||||
import { Lifetime } from "awilix"
|
||||
import {
|
||||
ProductService as MedusaProductService,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
// extending ProductService from the core
|
||||
class ProductService extends MedusaProductService {
|
||||
// The default life time for a core service is SINGLETON
|
||||
static LIFE_TIME = Lifetime.SCOPED
|
||||
|
||||
constructor(container, options) {
|
||||
super(...arguments)
|
||||
|
||||
// use the registered resource.
|
||||
try {
|
||||
container.customResource
|
||||
} catch (e) {
|
||||
// avoid errors when the backend first loads
|
||||
}
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ProductService
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: 'AwilixResolutionError: Could Not Resolve X',
|
||||
content: <ServiceLifetimeSection />
|
||||
},
|
||||
{
|
||||
title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)',
|
||||
content: <CustomRegistrationSection />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Store API reference](/api/store)
|
||||
- [Admin API reference](/api/admin)
|
||||
Reference in New Issue
Block a user