Skip to main content

​
Installation

Include the Komerza client library via CDN. Add this script tag to your HTML: 
<script src="https://cdn.komerza.com/komerza.min.js"></script>
The library is available globally as komerza after the script loads.

​
CDN Benefits

  • No build step required - Works with plain HTML/CSS/JS
  • Always up-to-date - Latest version automatically delivered
  • Fast loading - Cached globally via CDN
  • Lightweight - Minimal impact on page load time

​
Initialization

Initialize the library with your store ID before using any other functions: 
komerza.init("your-store-id");
You must call init() before using any other komerza function. All other functions will fail if the library hasn’t been initialized.

​
Finding Your Store ID

Your store ID is available in your Komerza dashboard. It’s a unique identifier for your store, typically in UUID format.

​
Example

<!DOCTYPE html>
<html>
  <head>
    <title>My Store</title>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
  </head>
  <body>
    <div id="store-name"></div>

    <script>
      // Initialize with your store ID
      komerza.init("550e8400-e29b-41d4-a716-446655440000");

      // Now you can use other komerza functions
      komerza.getStore().then((response) => {
        if (response.success) {
          document.getElementById("store-name").textContent =
            response.data.name;
        }
      });
    </script>
  </body>
</html>

​
When to Initialize

Call init() once when your page loads, before using any other komerza methods: ✅ Good - Initialize on page load: 
<script>
  // Initialize immediately komerza.init('your-store-id'); // Then use other
  functions displayProducts();
</script>
❌ Bad - Using methods before init: 
<script>
  // This will fail - init not called yet komerza.getStore(); // Error!
  komerza.init('your-store-id');
</script>

​
Framework Integration

​
Vanilla JavaScript

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
  </head>
  <body>
    <script>
      komerza.init("your-store-id");
    </script>
  </body>
</html>

​
React

import { useEffect } from "react";

function App() {
  useEffect(() => {
    // Initialize when component mounts
    if (window.komerza) {
      window.komerza.init("your-store-id");
    }
  }, []);

  return <div>My Store</div>;
}

​
Vue

<script>
export default {
  mounted() {
    // Initialize when component mounts
    if (window.komerza) {
      window.komerza.init("your-store-id");
    }
  },
};
</script>

​
Svelte

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    // Initialize when component mounts
    if (window.komerza) {
      window.komerza.init('your-store-id');
    }
  });
</script>

​
Build Process

The Komerza client library works with any framework or build process—the script runs in the browser regardless of how you build your site. Use any framework:
  • Plain HTML/CSS/JS (no build needed)
  • React, Vue, Svelte, Angular
  • Next.js, Nuxt, SvelteKit, Astro
  • Webpack, Vite, Rollup, Parcel
Hosting requirement: To host your storefront on Komerza infrastructure or list it on the theme marketplace, your project must compile to static HTML/CSS/JS files. Server-side rendering at runtime is not supported.

​
TypeScript Support

If you’re using TypeScript, you can add type definitions: 
declare global {
  interface Window {
    komerza: {
      init(storeId: string): void;
      getStore(): Promise<ApiResponse<Store>>;
      getBasket(): BasketItem[];
      checkout(email: string, coupon?: string): Promise<ApiResponse<Order>>;
      // ... other methods
    };
  }
}

// Use with types
window.komerza.init("your-store-id");
Type definitions are available in the script.json file for reference.

​
Verification

Verify the library is loaded and initialized correctly: 
// Check if library is loaded
if (typeof komerza === "undefined") {
  console.error("Komerza library not loaded");
} else {
  console.log("Komerza library loaded successfully");

  // Initialize
  komerza.init("your-store-id");

  // Verify initialization by fetching store
  komerza.getStore().then((response) => {
    if (response.success) {
      console.log("Store loaded:", response.data.name);
    } else {
      console.error("Failed to load store:", response.message);
    }
  });
}

​
Troubleshooting

“komerza is not defined”
  • Make sure the script tag is loaded before your code runs
  • Check browser console for script loading errors
  • Verify the CDN URL is correct
“Komerza.init must be called before using this method”
  • Call komerza.init() before using other functions
  • Ensure init is called only once per page load
Store not loading
  • Verify your store ID is correct (check dashboard)
  • Check browser console for API errors
  • Ensure you’re connected to the internet

​
Next Steps

Now that you’ve initialized the library, learn how to use it:

Store Information

Fetch store details, logo, and banner

Products

Display and manage product listings

Basket Management

Handle shopping cart operations

Checkout

Process orders and payments