3.1. Framework Overview
In this chapter, you'll learn about the Medusa Framework and how it facilitates building customizations in your Medusa application.
What is the Medusa Framework?#
All commerce application require some degree of customization. So, it's important to choose a platform that facilitates building those customizations.
When you build customizations with other ecommerce platforms, they require you to pull data through HTTP APIs, run custom logic that span across systems in a separate application, and manually ensure data consistency across systems. This adds significant overhead and slows down development as you spend time managing complex distributed systems.
The Medusa Framework eliminates this overhead by providing powerful low-level APIs and tools that let you build any type of customization directly within your Medusa project. You can build custom features, orchestrate operations and query data seamlessy across systems, extend core functionality, and automate tasks in your Medusa application.
With the Medusa Framework, you can focus your efforts on building meaningful business customizations and continuously delivering new features.
Using the Medusa Framework, you can build customizations like:
- Product Reviews
- Deep integration with an ERP system
- CMS integration with seamless content retrieval
- Custom item pricing in the cart
- Automated restock notifications
- Re-usable payment provider integrations
Framework Concepts and Tools#
Build Custom Features#
The Medusa Framework allows you to build custom features tailored to your business needs.
To create a custom feature, you can create a module that contains your feature's data models and the logic to manage them. A module is integrated into your Medusa application without side effects.
Then, you can build commerce features and flows in workflows that use your module. By using workflows, you benefit from features like rollback mechanism and retry configuration.
Finally, you can expose your custom feature with API routes that are built on top of your module and workflows.
1import type {2 MedusaRequest,3 MedusaResponse,4} from "@medusajs/framework/http"5import { createPostWorkflow } from "../../../workflows/create-post"6 7type PostRequestBody = {8 title: string9}10 11export const POST = async (12 req: MedusaRequest<PostRequestBody>,13 res: MedusaResponse14) => {15 const { result } = await createPostWorkflow(req.scope)16 .run({17 input: result.validatedBody,18 })19 20 return res.json(result)21}
Examples#
The following tutorials are step-by-step guides that show you how to build custom features using the Medusa Framework.
Start Learning#
To learn more about the different concepts useful for building custom features, check out the following chapters:
Extend Existing Features#
The Medusa Framework is flexible and extensible, allowing you to extend and build on top of existing models and features.
To associate new properties and relations with an existing model, you can create a module with data models that define these additions. Then, you can define a module link that associates two data models from separate modules.
Then, you can hook into existing workflows to perform custom actions as part of existing features and flows. For example, you can create a brand when a product is created.
1import { createProductsWorkflow } from "@medusajs/medusa/core-flows"2import { StepResponse } from "@medusajs/framework/workflows-sdk"3import { Modules } from "@medusajs/framework/utils"4import { LinkDefinition } from "@medusajs/framework/types"5import { BRAND_MODULE } from "../../modules/brand"6import BrandModuleService from "../../modules/brand/service"7 8createProductsWorkflow.hooks.productsCreated(9 (async ({ products, additional_data }, { container }) => {10 if (!additional_data?.brand_id) {11 return new StepResponse([], [])12 }13 14 const brandModuleService: BrandModuleService = container.resolve(15 BRAND_MODULE16 )17 18 const brand = await brandModuleService.createBrands({19 name: additional_data.brand_name,20 })21 })22)
You can also build custom workflows using your custom module and Medusa's modules, and use existing workflows and steps within your custom workflows.
Examples#
The following tutorials are step-by-step guides that show you how to extend existing features using the Medusa Framework.
Start Learning#
To learn more about the different concepts useful for extending features, check out the following chapters:
Integrate Third-Party Services#
The Medusa Framework provides the tools and infrastructure to build a middleware solution for your commerce ecosystem. You can integrate third-party services, perform operations across systems, and query data from multiple sources.
Orchestrate Operations Across Systems#
The Medusa Framework solves one of the biggest hurdles for ecommerce platforms: orchestrating operations across systems. Medusa has a built-in durable execution engine to help complete tasks that span multiple systems.
You can integrate a third-party service in a module. This module provides an interface to perform operations with the third-party service.
Then, you can build workflows that perform operations across systems. In the workflow, you can use your module to interact with the integrated third-party service.
For example, you can create a workflow that syncs products from your ERP system to your Medusa application.
By using a workflow to manage operations across systems, you benefit from features like rollback mechanism, background long-running execution, retry configuration, and more. This is essential for building a middleware solution that performs operations across systems, as you don't have to worry about data inconsistencies or failures.
You can then execute this workflow at a specific interval using scheduled jobs or when an event occurs using events and subscribers. You can also expose its features to client applications using an API route.
Examples
The following tutorials are step-by-step guides that show you how to orchestrate operations across third-party services using the Medusa Framework.
Start Learning
To learn more about the different concepts useful for integrating third-party services, check out the following chapters:
Query Data Across Systems#
Another essential feature for integrating third-party services is querying data across those systems efficiently.
The Framework allows you to build links not only between Medusa data models, but also virtual data models using read-only module links. You can build a module that provides the logic to query data from a third-party service, then create a read-only link between an existing data model and a virtual one from the third-party service.
Then, you can use Query to retrieve a product and its brand from the third-party service in a single query.
Query simplifies the process of retrieving data across systems, as you can retrieve data from multiple sources in a single query.
Examples
The following tutorials are step-by-step guides that show you how to query data across systems using the Medusa Framework.
Start Learning
To learn more about the different concepts useful for querying data across systems, check out the following chapters:
Automate Tasks#
The Medusa Framework provides the tools to automate tasks in your Medusa application. Automation is useful when you want to perform a task periodically, such as syncing data, or when an event occurs, such as sending a confirmation email when an order is placed.
To build the task to be automated, you first create a workflow that contains the task's logic, such as syncing data or sending an email.
Then, you can execute this workflow when an event occurs using a subscriber, or at a specific interval using a scheduled job.
Examples#
The following guides are step-by-step guides that show you how to automate tasks using the Medusa Framework.
Start Learning#
To learn more about the different concepts useful for automating tasks, check out the following chapters:
Re-Use Customizations Across Applications#
If you have custom features that you want to re-use across multiple Medusa applications, or you want to publish your customizations for the community to use, you can build a plugin.
A plugin encapsulates your customizations in a single package. The customizations include modules, workflows, API routes, and more.
You can then publish that plugin to NPM and install it in any Medusa application. This allows you to re-use your customizations efficiently across multiple projects, or share them with the community.
Examples#
The following tutorials are step-by-step guides that show you how to build plugins using the Medusa Framework.
Start Learning#
To learn more about the different concepts useful for building plugins, check out the following chapters: