# @medusajs/framework

> Framework

Latest version **2.22.7** (published 2026-11-13) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @medusajs/framework
pnpm add @medusajs/framework
yarn add @medusajs/framework
bun add @medusajs/framework
```

Provides the command `medusa-mikro-orm`.

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.22.7 |
| Published | 2026-11-13 |
| First published | 2024-07-29 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.22.0 |
| Dependencies | 26 |
| Unpacked size | 635.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 36586 |
| Author | Medusa |
| Maintainers | sebrindom, nicolas-gorga, sradevski, olijuhl, shahednasser |

## Links

- npm: https://www.npmjs.com/package/@medusajs/framework
- Repository: https://github.com/medusajs/medusa
- Homepage: https://github.com/medusajs/medusa#readme
- Issues: https://github.com/medusajs/medusa/issues
- npm.io page: https://npm.io/package/@medusajs/framework

## Dependencies (26)

- [cors](https://npm.io/package/cors.md) ^2.8.5
- [glob](https://npm.io/package/glob.md) 14.0.2
- [morgan](https://npm.io/package/morgan.md) ^1.12.0
- [express](https://npm.io/package/express.md) ^4.21.0
- [chokidar](https://npm.io/package/chokidar.md) ^6.0.0
- [compression](https://npm.io/package/compression.md) ^1.8.2
- [http-errors](https://npm.io/package/http-errors.md) 2.0.0
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^9.0.2
- [connect-redis](https://npm.io/package/connect-redis.md) 5.2.0
- [cookie-parser](https://npm.io/package/cookie-parser.md) ^1.4.6
- [@medusajs/deps](https://npm.io/package/@medusajs/deps.md) 2.22.7
- [@types/express](https://npm.io/package/@types/express.md) ^4.17.21
- [lodash.memoize](https://npm.io/package/lodash.memoize.md) ^4.1.2
- [path-to-regexp](https://npm.io/package/path-to-regexp.md) ^9.0.0
- [tsconfig-paths](https://npm.io/package/tsconfig-paths.md) ^4.2.0
- [@medusajs/types](https://npm.io/package/@medusajs/types.md) 2.22.7
- [@medusajs/utils](https://npm.io/package/@medusajs/utils.md) 2.22.7
- [express-session](https://npm.io/package/express-session.md) ^1.19.0
- [connect-dynamodb](https://npm.io/package/connect-dynamodb.md) ^3.0.5
- [@jercle/yargonaut](https://npm.io/package/@jercle/yargonaut.md) ^1.1.5
- [@medusajs/telemetry](https://npm.io/package/@medusajs/telemetry.md) 2.22.7
- [zod-validation-error](https://npm.io/package/zod-validation-error.md) 5.0.0
- [@medusajs/modules-sdk](https://npm.io/package/@medusajs/modules-sdk.md) 2.22.7
- [@medusajs/orchestration](https://npm.io/package/@medusajs/orchestration.md) 2.22.7
- [@medusajs/workflows-sdk](https://npm.io/package/@medusajs/workflows-sdk.md) 2.22.7
- [@aws-sdk/client-dynamodb](https://npm.io/package/@aws-sdk/client-dynamodb.md) ^3.1156.0

## Recent versions

- 2.22.7 (latest) — 2026-11-13
- 2.22.8-preview-20261117142131 (preview) — 2026-11-17
- 2.22.7-snapshot-20261113105900 (snapshot) — 2026-11-13
- 2.16.0-options-preview-20260605124754 (options-preview) — 2026-06-05
- 2.0.0-rc-20241022183311 (rc) — 2024-10-22
- 2.22.7-preview-20261113113415 — 2026-11-13
- 2.22.7-preview-20261113102906 — 2026-11-13
- 2.22.7-snapshot-20261113095001 — 2026-11-13
- 2.22.7-preview-20261113085903 — 2026-11-13
- 2.22.7-preview-20261113084204 — 2026-11-13
- 2.22.7-snapshot-20261112111749 — 2026-11-12
- 2.22.7-snapshot-20261111153147 — 2026-11-11
- 2.22.6 — 2026-11-09
- 2.22.5 — 2026-11-09
- 2.22.4 — 2026-11-06
- … 198 more at https://npm.io/package/@medusajs/framework/versions

## README

<p align="center">
  <a href="https://www.medusajs.com">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
    </picture>
  </a>
</p>
<h1 align="center">
  @medusajs/framework
</h1>

<h4 align="center">
  <a href="https://docs.medusajs.com">Documentation</a> |
  <a href="https://www.medusajs.com">Website</a>
</h4>

<p align="center">
  Building blocks for digital commerce
</p>
<p align="center">
  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
  </a>
  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
  </a>
  <a href="https://discord.gg/xpCwq3Kfn8">
    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
  </a>
  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
  </a>
</p>

`@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:

```bash
npm install @medusajs/framework
```

## Usage

```ts
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:

```ts
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.

## Resources

- [Framework overview](https://docs.medusajs.com/learn/fundamentals/framework)
- [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes)
- [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows)
- [Modules](https://docs.medusajs.com/learn/fundamentals/modules)
- [Data models](https://docs.medusajs.com/learn/fundamentals/data-models)
- [Medusa configuration](https://docs.medusajs.com/learn/configurations/medusa-config)

---
_Source: https://npm.io/package/@medusajs/framework · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
