sveltekit-medusa-client

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.

• A handler in Copy to clipboardhooks.server.js/ts
• A page load function in Copy to clipboard+page.server.js/ts
• A form action in Copy to clipboard+page.server.js/ts, or
• An API endpoint, aka Copy to clipboard+server.js/ts

Example Project

Installation

12

yarn add sveltekit-medusa-client

1
MEDUSA_BACKEND_URL="http://localhost:9000"

Basic Usage

123456789
import { MedusaClient } from 'sveltekit-medusa-client'
import { MEDUSA_BACKEND_URL } from '$env/static/private'

export const load = async function () {
   const medusa = new MedusaClient(MEDUSA_BACKEND_URL)
   return {
      products: medusa.getProducts()
   }
}

12345678910111213141516
<script>
   export let data
   const products = data.products  
</script>

<ul>
{#each products as product}
   <li>
      Product id: {product.id}<br>
      Product handle: {product.handle}<br>
      {product.title}
   </li>
{:else}
   <p>No products returned</p>
{/each}
<ul>

Using the Client as a Singleton

123
import { MedusaClient } from 'sveltekit-medusa-client'
import { MEDUSA_BACKEND_URL } from '$env/static/private'
export default new MedusaClient(MEDUSA_BACKEND_URL)

1234567
import medusa from '$lib/server/medusa'

export const load = async function () {
   return {
      products: medusa.getProducts()
   }
}

Client Options

1234567891011
export interface ClientOptions {
   retry?: number
   timeout?: number
   headers?: {}
   persistentCart?: boolean
   logger?: Logger
   logFormat?: 'text' | 'json' | 'majel'
   logLevel?: 'verbose' | 'limited' | 'silent'
   excludedPaths?: string[]
   limitedPaths?: string[]
}

12345678910111213141516
import { MedusaClient } from 'sveltekit-medusa-client'
import { MEDUSA_BACKEND_URL, CLOUDFLARE_ACCESS_ID, CLOUDFLARE_ACCESS_SECRET } from '$env/static/private'
export default new MedusaClient(MEDUSA_BACKEND_URL, { 
   timeout: 3000, // 3 seconds
   retry: 0,
   headers: {
      'CF-Access-Client-Id': CLOUDFLARE_ACCESS_ID,
      'CF-Access-Client-Secret': CLOUDFLARE_ACCESS_SECRET,
   },
   persistentCart: true,
   logger: console,
   logFormat: 'json',
   logLevel: 'verbose',
   excludedPaths: ['/store/mycustomsensitiveroute'],
   limitedPaths: ['/store/bulkyresponseroute']
})

• Copy to clipboardtimeout
  • The default is 8000, or 8 seconds. The length of time to wait for a response before aborting
• Copy to clipboardretry
  • The default is 3. The number of times to retry a timed out request
• Copy to clipboardheaders
  • The default is undefined. An object of HTTP headers, as many as you want, which will be added to all requests sent to the backend. This can be useful in many situations. If you would like to access a server behind a proxy with bearer auth, you can pass the auth header in this property. You can also pass Cloudflare Access service auth credentials, as in the example above.
• Copy to clipboardpersistentCart
  • The default is false. If true, the client will expect an endpoint at Copy to clipboard/store/customers/me/cart that will return the customer's cart. For now, this endpoint is not included in the Medusa core and must be added.
• Copy to clipboardlogger
  • The default is Copy to clipboardconsole. You can inject your own logger instance if you already have one configured in the application. For example, a winston logger instance. Any logger that implements the Copy to clipboardinfo() and Copy to clipboarderror() methods should work.
• Copy to clipboardlogFormat
  • The default is json. You can change to 'text' if you need to for some reason.
• Copy to clipboardexcludedPaths
  • The default is ['/store/auth']. An array of strings that should be checked to exclude paths from logging. The default can be added to, but not overridden. Requests to URIs on your medusa backend that contain one or more of these strings will not be logged.
• Copy to clipboardlimitedPaths
  • The default is undefined. An array of strings that should be checked to reduce the level of detail when logging. Requests to URIs on your medusa backend that contain one or more of these strings will not log request or response content, only metadata. The url of the request will be logged, but not query params.

Authentication

123456
import medusa from '$lib/server/medusa'

export const handle = async ({ event, resolve }) => {
   event = await medusa.handleRequest(event)
   return await resolve(event)
}

1234567
import medusa from '$lib/server/medusa'

export const load = async function ({ locals, cookies }) {
   return {
      cart: medusa.getCart(locals, cookies)
   }
}

Caching

Caching Example

1
let product = await medusa.getProduct(handle, { key: `__${handle}__product`, ttl: 10000 })

Important Notes

• Short cache times are recommended. Even a short ttl can lead to a significant performance boost in your storefront application and reduction of load on your Medusa backend on high traffic sites.
• The cache is stored in memory. This is ideal in some scenarios, but not in memory-constrained environments or for especially large sites.
• When deploying to a serverless platform, you will probably want to use something like Redis in your storefront application for caching and forgo the built-in cache option.

The Cache is a Shared, Server-Side Cache

• Never attempt to cache cart or customer-specific information. Only functions that return data that can be safely shared across customers support cache options.
• The list of functions that support caching:

1234567
getSearchResults(q:string, cacheOptions?:CacheOptions)
getProducts(options?:ProductRetrievalOptions, cacheOptions?:CacheOptions)
getCollections(options?:CollectionRetrievalOptions, cacheOptions?:CacheOptions)
getCollection(handle:string, cacheOptions?:CacheOptions)
getCollectionProducts(id:string, options?:ProductRetrievalOptions, cacheOptions?:CacheOptions)
getProduct(handle:string, cacheOptions?:CacheOptions)
getReviews(productId:string, options?:ReviewRetrievalOptions, cacheOptions?:CacheOptions)

Make Sure Your Key is Unique

Cache Bypass

Cache Bust

12345
let product = await medusa.getProduct(handle, { 
   key: `__${handle}__product`, 
   ttl: 10000,
   revalidate: true
})