Connect Your Storefront to Medusa

In this guide, you’ll learn how to send requests from your storefront application to the Medusa application.

Connect to the Medusa Application#

To send requests from the storefront to the Medusa application’s Store API Routes, you have two options:

• For JavaScript frameworks: use Medusa’s JS SDK in any JavaScript framework. This NPM package facilitates interacting with the backend’s REST APIs. All Storefront Development guides use the JS SDK.
• For other frontend technologies: interact directly with the Medusa application by sending requests to its Store REST APIs.

Set Up the JS SDK#

To set up the JS SDK in your storefront application, install the @medusajs/js-sdk package with the types package:

yarn
pnpm
npm

Then, create a file that initializes the JS SDK client. For example, create the file src/lib/sdk.ts with the following content:

src/lib/sdk.ts
1import Medusa from "@medusajs/js-sdk"2
3let MEDUSA_BACKEND_URL = "http://localhost:9000"4
5if (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {6  MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL7}8
9export const sdk = new Medusa({10  baseUrl: MEDUSA_BACKEND_URL,11  debug: process.env.NODE_ENV === "development",12  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,13})

Where:

• NEXT_PUBLIC_MEDUSA_BACKEND_URL is the URL of your Medusa application. Based on your storefront framework, make sure the environment variable is accessible in the browser. For example, in Next.js, prefix the variable name with NEXT_PUBLIC_.
• NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY is the publishable API key of your storefront. Learn more in the Publishable API Keys guide.

You can then import the sdk instance from src/lib/sdk.ts and use it to send requests to the Medusa application. For example:

Code
1import { sdk } from "@/lib/sdk"2
3sdk.store.product.list()4.then(({ products }) => {5  console.log(products)6})

Refer to the JS SDK reference to learn more about using the SDK to interact with the Medusa application.

Configure Store CORS in Medusa#

The Medusa application’s API routes are guarded by a CORS middleware. Make sure to set the storeCors property of the http configuration in medusa-config.ts to the storefront’s URL.

For example:

Medusa Application
medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    http: {4      storeCors: "http://localhost:3000,http://localhost:8000",5      // ...6    },7  },8  // ...9})

Refer to the Medusa configuration guide to learn more about configuring CORS in the Medusa application.

Add Search to Your Storefront#

The JS SDK sends requests to Medusa’s Store API routes, which is enough for listing and filtering by a field’s exact value. For a search experience with full-text search, facets, and sorting, use the InstantSearch adapter instead. It’s the recommended approach since Medusa v2.21.1, and it requires the Search Module configured with a provider in your Medusa application.

InstantSearch is a family of UI widget libraries, available for React, Vue, Angular, and plain JavaScript. The @medusajs/instantsearch-adapter package provides the search client that connects those widgets to Medusa: it converts each widget’s request into a Medusa search query, sends it to the /store/search API route, and converts the results back.

The adapter reuses the SDK instance you created above, so it sends the publishable API key and other headers the same way. For example, create the file src/lib/search-client.ts with the following content:

src/lib/search-client.ts
1import {2  createInstantSearchAdapter,3} from "@medusajs/instantsearch-adapter"4import { sdk } from "./sdk"5
6export const PRODUCT_INDEX_NAME = "product"7
8export const { searchClient } = createInstantSearchAdapter({9  sdk,10  path: "/store/search",11})

You then pass searchClient and PRODUCT_INDEX_NAME to an InstantSearch provider, and add the widgets for the search box, results, filters, sorting, and pagination inside it.

Refer to the InstantSearch Adapter guide to install the adapter and build the search interface, and to the Filtering, Sorting, and Pagination guide to add refinements to the results.