Menu
  • Get Started
  • Product
  • Resources
  • Tools & SDKs
  • Framework
  • Reference

Medusa JS SDK

In this documentation, you'll learn how to install and use Medusa's JS SDK.

What is Medusa JS SDK?#

Medusa's JS SDK is a library to easily send requests to your Medusa application. You can use it in your admin customizations or custom storefronts.

How to Install Medusa JS SDK?#

The Medusa JS SDK is available in your Medusa application by default. So, you don't need to install it before using it in your admin customizations.

To install the Medusa JS SDK in other projects, such as a custom storefront, run the following command:

You install two libraries:

  • @medusajs/js-sdk: the Medusa JS SDK.
  • @medusajs/types: Medusa's types library, which is useful if you're using TypeScript in your development.

Setup JS SDK#

In your project, create the following config.ts file:

Note: For admin customizations, create this file at src/admin/lib/config.ts.

JS SDK Configurations#

The Medusa initializer accepts as a parameter an object with the following properties:

PropertyDescriptionDefault

baseUrl

A required string indicating the URL to the Medusa backend.

-

publishableKey

A string indicating the publishable API key to use in the storefront. You can retrieve it from the Medusa Admin.

This is required for storefront applications. Otherwise, all requests will fail.

-

auth.type

A string that specifies the user authentication method to use.

Possible types are:

  • session: The user is authenticated with a cookie session.
  • jwt: The user is authenticated with a JWT token that's passed in the Bearer authorization header.

-

auth.jwtTokenStorageKey

A string that, when auth.type is jwt, specifies the key of the JWT token in the storage specified in the auth.jwtTokenStorageMethod configuration.

medusa_auth_token

auth.jwtTokenStorageMethod

A string that, when auth.type is jwt, specifies where the JWT token is stored. Possible values are:

  • local for the Local Storage.
  • session for the Session Storage.
  • memory to store it within the SDK for the current application's runtime.

local

auth.fetchCredentials

By default, if auth.type is session, the credentials: include option is passed in fetch requests under the hood. However, some platforms or environments may not support passing this option.

This option accepts a string to configure the value of credentials when the authentication type is session. It accepts one of the following values:

  • include: (default) to pass the credentials: include option.
  • omit: to pass the credentials: omit option.
  • same-origin: to pass the credentials: same-origin option.

This option is only available after Medusa v2.1.1.

local

globalHeaders

An object of key-value pairs indicating headers to pass in all requests, where the key indicates the name of the header field.

-

apiKey

A string indicating the admin user's API key. If specified, it's used to send authenticated requests.

-

debug

A boolean indicating whether to show debug messages of requests sent in the console. This is useful during development.

false

logger

Replace the logger used by the JS SDK to log messages. The logger must be a class or object having the following methods:

  • error: A function that accepts an error message to log.
  • warn: A function that accepts a warning message to log.
  • info: A function that accepts an info message to log.
  • debug: A function that accepts a debug message to log.

JavaScript's console is used by default.

Send Requests to Custom Routes#

The sidebar shows the different methods that you can use to send requests to Medusa's API routes.

To send requests to custom routes, the JS SDK has a client.fetch method that wraps the JavaScript Fetch API that you can use. The method automatically appends configurations and headers, such as authentication headers, to your request.

For example, to send a request to a custom route at http://localhost:9000/custom:

The fetch method accepts as a first parameter the route's path relative to the baseUrl configuration you passed when you initialized the SDK.

In the second parameter, you can pass an object of request configurations. You don't need to configure the content-type to be JSON, or stringify the body or query value, as that's handled by the method.

The method returns a Promise that, when resolved, has the data returned by the request. If the request returns a JSON object, it'll be automatically parsed to a JavaScript object and returned.

Medusa JS SDK Tips#

Use Tanstack (React) Query in Admin Customizations#

In admin customizations, use Tanstack Query with the JS SDK to send requests to custom or existing API routes.

Tanstack Query is installed by default in your Medusa application.

Use the configured SDK with the useQuery Tanstack Query hook to send GET requests, and useMutation hook to send POST or DELETE requests.

For example:

Refer to Tanstack Query's documentation to learn more about sending Queries and Mutations.

Cache in Next.js Projects#

Every method of the SDK that sends requests accepts as a last parameter an object of key-value headers to pass in the request.

In Next.js storefronts or projects, pass the next.tags header in the last parameter for data caching.

For example:

Code
1sdk.store.product.list({}, {2  next: {3    tags: ["products"],4  },5})

The tags property accepts an array of tags that the data is cached under.

Then, to purge the cache later, use Next.js's revalidateTag utility:

Code
1import { revalidateTag } from "next/cache"2
3// ...4
5revalidateTag("products")

Learn more in the Next.js documentation.

Was this page helpful?
Edit this page