@medusajs/framework
Documentation | Website
Building blocks for digital commerce
@medusajs/framework is the Medusa Framework: the single package Medusa applications, plugins, and custom modules import from to build API routes, workflows, modules, data models, subscribers, scheduled jobs, and configuration. It re-exports the core libraries (@medusajs/utils, @medusajs/types, @medusajs/workflows-sdk, @medusajs/modules-sdk, @medusajs/orchestration) and pinned third-party dependencies through subpath entry points, so apps should import from @medusajs/framework/* instead of those packages directly.
At a glance
| Package | @medusajs/framework |
| Type | Core library |
| Import from | @medusajs/framework/<subpath> |
Entry points
| Import path | Provides |
|---|---|
@medusajs/framework/utils |
Re-export of @medusajs/utils: defineConfig, loadEnv, Modules, ContainerRegistrationKeys, MedusaError, MedusaService, Module, ModuleProvider, model, defineLink, and more |
@medusajs/framework/types |
Re-export of @medusajs/types: DTOs, module service interfaces, and the HttpTypes namespace |
@medusajs/framework/workflows-sdk |
Re-export of @medusajs/workflows-sdk: createWorkflow, createStep, StepResponse, WorkflowResponse, transform, when, createHook |
@medusajs/framework/workflows-sdk/composer |
Re-export of @medusajs/workflows-sdk/composer |
@medusajs/framework/modules-sdk |
Re-export of @medusajs/modules-sdk |
@medusajs/framework/orchestration |
Re-export of @medusajs/orchestration |
@medusajs/framework/http |
MedusaRequest, AuthenticatedMedusaRequest, MedusaResponse, defineMiddlewares, authenticate, validateAndTransformBody, validateAndTransformQuery, and the AuditRouteConfig type for a middleware route's audit setting |
@medusajs/framework/subscribers |
SubscriberArgs, SubscriberConfig |
@medusajs/framework/jobs |
Scheduled job loader and types |
@medusajs/framework/logger |
The Medusa logger |
@medusajs/framework/config |
Config loader and ConfigModule types |
@medusajs/framework/telemetry |
Tracer for OpenTelemetry instrumentation |
@medusajs/framework/feature-flags |
Feature flag loader and router |
@medusajs/framework/database, /links, /search, /workflows, /migrations, /build-tools |
Loaders and tooling used by the Medusa application and CLI |
@medusajs/framework/zod |
Re-export of the zod version Medusa uses |
@medusajs/framework/awilix, /pg |
Re-exports of awilix and pg |
@medusajs/framework/mikro-orm/{core,knex,postgresql,migrations,cli} |
Re-exports of the pinned MikroORM packages |
@medusajs/framework/opentelemetry/{api,resources,sdk-node,sdk-trace-node,instrumentation-pg} |
Re-exports of the pinned OpenTelemetry packages |
The package also ships a medusa-mikro-orm binary that wraps the MikroORM CLI.
Installation
Projects created with create-medusa-app already include it. To add it to a plugin or module package:
npm install @medusajs/framework
Usage
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
export const GET = (
req: MedusaRequest,
res: MedusaResponse
) => {
res.json({
message: "[GET] Hello world!",
})
}
Audit settings
When the Audit Module is installed, POST, PUT, PATCH, and DELETE requests under /admin, /rbac, and /auth are recorded as audit logs. Set audit on a middleware route to change that for the routes it matches:
import { defineMiddlewares } from "@medusajs/framework/http"
export default defineMiddlewares({
routes: [
{
matcher: "/admin/brands",
methods: ["POST"],
// Recorded as `brand.create` with the created brand's ID by default.
audit: { requestData: (req) => ({ name: req.validatedBody?.name }) },
},
{ matcher: "/admin/brands/sync", methods: ["POST"], audit: false },
// Routes outside `/admin`, `/rbac`, and `/auth` are recorded once opted in.
{ matcher: "/vendors*", methods: ["POST", "DELETE"], audit: true },
],
})
Request and response bodies are never stored, only what requestData and responseData return.