sveltekit-medusa-client
A client library for communicating with a Medusa ecommerce backend in SvelteKit
If you are not familiar with Medusa, you can learn more on the project web site.
Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm.
This client is designed to be used on the server. It cannot be exported to the browser. This means you must make your calls to your Medusa backend from your storefront server, not from the client browser. Calls to the library can be made from:
- A handler in Copy to clipboard
hooks.server.js/ts
- A page load function in Copy to clipboard
+page.server.js/ts
- A form action in
, orCopy to clipboard+page.server.js/ts
- An API endpoint, aka Copy to clipboard
+server.js/ts
One of the benefits of newer frameworks like SvelteKit is that they combine the fluid user experience of client-side reactivity with the ability to handle logic on the server when you choose to. Keeping your Medusa backend firewalled and accessible only to your storefront application server provides an additional layer of security versus having your backend directly exposed. This type of deployment also allows us to use tools like Turnstile or reCAPTCHA to provide some protection against bots and brute force attacks. Without firewalling your backend, it would not be of much use to implement turnstile protection on your frontend. It could easily be bypassed.
Installation
Create a new SvelteKit app if needed. Then, install this package.
You should set the location of your Medusa server as an environment variable. For example:
Copy to clipboard.env
Basic Usage
To create a new client, invoke the MedusaClient constructor, passsing the location of your Medusa server as an argument. For example:
Copy to clipboard+page.server.js
Then, on the corresponding
, you can use the products data you exported: (For more information on the data returned, refer to the Medusa API Documentation)Copy to clipboard+page.svelte
Using the Client as a Singleton
One major drawback of the example above is that a new Medusa client is created for each page load.
You can prevent that by adding a small library in your project that creates a single shared client that can be imported where needed. For example:
You can prevent that by adding a small library in your project that creates a single shared client that can be imported where needed. For example:
Copy to clipboardlib/server/medusa.js
Now, on our
load function, we can do this:Copy to clipboard+page.server.js
Authentication
Some methods in the library, like the
method in the example above, need no authentication. Other methods need more context, such as whether the requester is a logged in user, or whether they have an existing shopping cart. The first argument passed to those methods is the special SvelteKitCopy to clipboardgetAllProducts
object. Locals on the server work much like a page or session store in the browser. They are a place to hold on to data related to this particular request that we may need somewhere else in the application before this request/response cycle is complete.Copy to clipboardlocals
Use the middleware method
from this library to handle customer authentication on every request with very little effort. If the user is logged in, the user object will be available atCopy to clipboardhandleRequest
Middleware is added in SvelteKit via the hooks.server.js/ts file:Copy to clipboardlocals.user.
Copy to clipboardhooks.server.js
Now, we can invoke methods that require information about the user and the cart.
Copy to clipboard+page.server.js
Versioning
Medusa is under heavy development, and breaking changes do occur. Once this library achieves release candidate stage, versioning will match the corresponding @medusajs/medusa version number the library is intended to be used with.
For example:
Package | Version |
---|---|
Medusa backend | 1.8.2 |
Corresponding client | 1.8.2 (and, if necessary, 1.8.2b, 1.8.2c, etc) |

Build your own plugins
Develop your own plugins with our API to speed up your processes.
Make your plugin available via npm for it to be shared in our Plugin Library with the broader Medusa community.
.png)