@medusajs/js-sdk
Documentation | Website
Building blocks for digital commerce
Medusa JS SDK: a JavaScript/TypeScript client for the Medusa Store and Admin API routes. Use it in storefronts, admin customizations, or any JavaScript app that sends requests to a Medusa application, including your custom API routes.
At a glance
| Package | @medusajs/js-sdk |
| Type | Core library |
| Import from | @medusajs/js-sdk (default export Medusa) |
| Entry points | ESM (import) and CommonJS (require) builds |
Features
sdk.storemethods for the Store API routes, such as products, carts, and customers.sdk.adminmethods for the Admin API routes.sdk.authmethods to register, log in, log out, and reset passwords for any actor type, such ascustomeroruser.sdk.client.fetchto send requests to custom API routes with the configured headers and authentication.sdk.setLocaleto send thex-medusa-localeheader with every request.
Installation
npm install @medusajs/js-sdk @medusajs/types
@medusajs/types is optional and provides the request and response types.
Usage
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
baseUrl: "http://localhost:9000",
debug: process.env.NODE_ENV === "development",
publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
})
const { products } = await sdk.store.product.list()
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
baseUrl |
string |
URL of the Medusa application. Required. | - |
publishableKey |
string |
Publishable API key, sent in the x-publishable-api-key header. Required for Store API routes. |
- |
apiKey |
string |
Secret API key, sent as Basic authentication. Use only on the server for Admin API routes. | - |
globalHeaders |
ClientHeaders |
Headers to send with every request. | - |
auth.type |
"jwt" | "session" |
How to authenticate. See Authentication types. | "jwt" |
auth.jwtTokenStorageMethod |
"local" | "session" | "memory" | "custom" | "nostore" |
Where to store the JWT token. | "local" in browsers, "nostore" otherwise |
auth.jwtTokenStorageKey |
string |
Storage key of the JWT token. | "medusa_auth_token" |
auth.storage |
CustomStorage |
Object with getItem, setItem, and removeItem methods. Required when jwtTokenStorageMethod is "custom". |
- |
auth.fetchCredentials |
"include" | "omit" | "same-origin" |
credentials of fetch requests when auth.type is "session". |
"include" |
logger |
Logger |
Logger with error, warn, info, and debug methods. |
console |
debug |
boolean |
Whether to log debug messages. | false |
Authentication types
"jwt"(default): after login, the SDK stores the JWT token based onauth.jwtTokenStorageMethodand sends it in theAuthorization: Bearerheader. Fetch requests usecredentials: "omit"."session": after login, the SDK exchanges the JWT token for a cookie session using the/auth/sessionAPI route, and sends requests withauth.fetchCredentials. Logging out deletes the session. Use it for the Medusa Admin and admin customizations.